Usage Analytics

The usage analytics endpoint is how you read raw usage data back out of MarginFront. It returns rolled-up event counts, quantity totals, and cost for any customer, agent, or time window you specify. Use it to:

Power “current period usage” widgets in your own product
Build cost dashboards that show your customers what they’ve used this month
Project a customer’s end-of-month bill before the invoice is generated
Feed data into your own BI tools

This is a read-only endpoint. It doesn’t create or modify anything.

Looking for revenue, margin, or MRR? This page covers the raw usage roll-up. For revenue and margin use /v1/analytics/revenue. For cost with breakdowns by agent, customer, signal, day, plan, or model use /v1/analytics/cost. For monthly recurring revenue use /v1/analytics/mrr.

The endpoint

Method & URL:

GET /v1/analytics/usage

Same auth as everything else: API key in the x-api-key header.

Query parameters

All optional. If you don’t specify any, you get a roll-up for the whole org over the default time window.

Param	Type	Description
`startDate`	ISO date	Start of the time window (inclusive).
`endDate`	ISO date	End of the time window (inclusive).
`customerId`	UUID	Filter to a single customer. Use MarginFront’s internal customer UUID (not your `externalId`).
`agentId`	UUID	Filter to a single agent.
`signalId`	UUID	Filter to a single signal.
`groupBy`	string	Time-bucket size for `timeSeriesData`. One of `"daily"`, `"weekly"`, `"monthly"`. Default: `"daily"`.
`breakdownBy`	string	Add a `dimensionBreakdown` section broken out by one of `"customer"`, `"signal"`, `"agent"`. When omitted, the response has no `dimensionBreakdown` field.

If you pass an invalid groupBy or breakdownBy value, the API returns 400 Bad Request with a message listing the accepted values.

Example curl calls

Get everything for April 2026:

curl "https://api.marginfront.com/v1/analytics/usage?startDate=2026-04-01&endDate=2026-04-30" \
  -H "x-api-key: mf_sk_test_..."

Get usage for one customer:

curl "https://api.marginfront.com/v1/analytics/usage?customerId=bc8eceda-50e4-4138-b2a2-47e92d344540&startDate=2026-04-01&endDate=2026-04-30" \
  -H "x-api-key: mf_sk_test_..."

Get weekly totals for one agent:

curl "https://api.marginfront.com/v1/analytics/usage?agentId=3a1948ea-a701-4752-8c3d-df6c2f5833cf&startDate=2026-04-01&endDate=2026-04-30&groupBy=weekly" \
  -H "x-api-key: mf_sk_test_..."

Break down totals by customer:

curl "https://api.marginfront.com/v1/analytics/usage?startDate=2026-04-01&endDate=2026-04-30&breakdownBy=customer" \
  -H "x-api-key: mf_sk_test_..."

What you get back (`200 OK`)

{
  "dateRange": {
    "start": "2026-04-01",
    "end": "2026-04-30",
    "groupBy": "daily"
  },
  "filters": {},
  "summary": {
    "totalEvents": 1247,
    "totalQuantity": 1247,
    "totalCost": 42.18,
    "avgCostPerEvent": 0.0338
  },
  "timeSeriesData": [
    {
      "date": "2026-04-01",
      "eventCount": 87,
      "totalQuantity": 87,
      "totalCost": 2.94
    },
    {
      "date": "2026-04-02",
      "eventCount": 93,
      "totalQuantity": 93,
      "totalCost": 3.12
    }
  ],
  "metadata": {
    "signals": {
      "69145379-8b26-4050-b54d-e08d6059ca18": "Messages Processed"
    },
    "customers": {
      "19a53f22-3cba-4224-bf1b-7b541ed7d12f": "Acme Inc"
    },
    "agents": {
      "84165d91-1136-4960-97d7-e24136476ce7": "Customer Support Bot"
    }
  }
}

When you pass breakdownBy, an additional dimensionBreakdown field appears at the top level:

{
  "dimensionBreakdown": {
    "dimensionType": "customer",
    "summary": [
      {
        "dimensionId": "19a53f22-3cba-4224-bf1b-7b541ed7d12f",
        "dimensionLabel": "Acme Inc",
        "totalEvents": 412,
        "totalQuantity": 412,
        "totalCost": 18.23
      }
    ],
    "timeline": [
      {
        "date": "2026-04-01",
        "dimensionId": "19a53f22-3cba-4224-bf1b-7b541ed7d12f",
        "dimensionLabel": "Acme Inc",
        "eventCount": 14,
        "totalQuantity": 14,
        "totalCost": 0.62
      }
    ]
  }
}

Understanding the response

summary: totals across the entire date range. This is what most dashboards want. Fields: totalEvents, totalQuantity, totalCost, avgCostPerEvent.
timeSeriesData: one row per time bucket (daily, weekly, or monthly depending on groupBy). Good for drawing charts. Note the row field is eventCount (not totalEvents).
metadata: lookup dictionaries mapping UUIDs to human-readable names for signals, customers, and agents referenced in the results. Use it to render labels without a second round-trip.
dimensionBreakdown: present only when you pass breakdownBy=customer|signal|agent. An object with dimensionType, a summary array (one row per dimension with totals across the window), and a timeline array (per-bucket rows tagged with the dimension).
dateRange and filters: echo back what you queried so the response is self-describing. filters contains only the keys you actually passed (it’s {} when you passed no filters).

Values in this endpoint are returned as numbers. That includes totalCost, totalQuantity, totalEvents, and avgCostPerEvent on summary, every field on timeSeriesData rows, and every field on dimensionBreakdown rows. (Contrast with GET /v1/events, where per-event usageCost and quantity are strings.) Analytics values are already rolled up, so sub-cent precision only shows up in averages.

Common errors

400 Bad Request: a query parameter is in the wrong format (e.g., startDate isn’t a valid ISO date).
401 Unauthorized: API key missing or wrong.

Using the Node SDK

// All usage this month for a specific customer
const stats = await mf.analytics.usage({
  customerId: "bc8eceda-50e4-4138-b2a2-47e92d344540",
  startDate: "2026-04-01",
  endDate: "2026-04-30",
});

console.log(`Customer used $${stats.summary.totalCost} worth of usage`);

What this endpoint is for (and what it isn’t)

Use this for:

Live dashboards, projections, “usage so far this month” displays
Triggering alerts when a customer hits a usage threshold
Feeding simple BI reports

Don’t use this for:

Revenue, margin, or MRR. Use /v1/analytics/revenue or /v1/analytics/mrr instead.
Cost broken down by agent / customer / signal / day / plan / model. Use /v1/analytics/cost instead.
Actual invoice data. Use invoices. Usage analytics gives you “here’s the raw usage roll-up,” but invoices are the finalized billing documents that include discounts, taxes, prorations, etc.
High-resolution per-event drill-down. This endpoint returns aggregates. For event-level detail, use the signal-events listing endpoint at GET /v1/events.

Resources

Reference

Analytics

Usage Analytics

The endpoint

Query parameters

Example curl calls

What you get back (`200 OK`)

Understanding the response

Common errors

Using the Node SDK

What this endpoint is for (and what it isn’t)

​Usage Analytics

​The endpoint

​Query parameters

​Example curl calls

​What you get back (200 OK)

​Understanding the response

​Common errors

​Using the Node SDK

​What this endpoint is for (and what it isn’t)

Usage Analytics

The endpoint

Query parameters

Example curl calls

What you get back (`200 OK`)

Understanding the response

Common errors

Using the Node SDK

What this endpoint is for (and what it isn’t)