> ## Documentation Index > Fetch the complete documentation index at: https://docs.marginfront.com/llms.txt > Use this file to discover all available pages before exploring further. # Analytics > Query rolled-up usage data # 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`](./analytics-revenue). For cost with breakdowns by agent, customer, signal, day, plan, or model use [`/v1/analytics/cost`](./analytics-cost). For monthly recurring revenue use [`/v1/analytics/mrr`](./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:** ```bash theme={null} 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:** ```bash theme={null} 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:** ```bash theme={null} 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:** ```bash theme={null} 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`) ```json theme={null} { "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: ```json theme={null} { "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 ```js theme={null} // 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`](./analytics-revenue) or [`/v1/analytics/mrr`](./analytics-mrr) instead. * **Cost broken down by agent / customer / signal / day / plan / model.** Use [`/v1/analytics/cost`](./analytics-cost) instead. * **Actual invoice data.** Use [invoices](./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`.