Cost Data API
Get organization-wide cost trend
Returns organization-wide time-series cost data. Call it with a GET request to /cost-data/trend, authenticated with a restricted API key and the "costs:read" scope.
Returns organization-wide time-series cost data. Can be filtered to one end user, filtered to one dimension value, or grouped by dimension. **Granularity** (not overridable): ranges up to 30 days return daily points, 31 to 90 days weekly, over 90 days monthly. **Modes:** - No filter params: Returns a single "Total" series (all costs) - `dimension_key` only: Returns top 5 dimension values as series + "Other" - `dimension_key` + `dimension_value`: Returns a single series filtered to that value - `end_user_id`: Returns a single series for that end user `dimension_key` must be a dimension registered for your organization; unknown keys return 404. `dimension_value` is only honored together with `dimension_key`; if sent alone the parameter is ignored and the unfiltered "Total" series is returned. If `dimension_key` or `dimension_value` is provided, `end_user_id` is ignored; do not combine them. Requests count toward your per-API-key rate limit; sustained overruns return 429 with the standard error envelope.
Authentication and scopes
Authenticate with a restricted API key in the Authorization: Bearer <key> header. This endpoint requires the costs:read scope.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
start_date | query | string | Yes | Start of date range (ISO 8601, inclusive). Must be before end_date. |
end_date | query | string | Yes | End of date range (ISO 8601, exclusive). |
end_user_id | query | string | No | Optional end user ID (UUID, as returned in /cost-data/by-end-user end_user_id) to filter the trend to one end user. Must be a UUID; the 'unassigned' bucket cannot be filtered here. Prefer GET /end-user-costs/{externalId}/trend for per-end-user analysis. |
dimension_key | query | string | No | Optional dimension key to filter or group by. Must be a dimension registered for your organization; unknown keys return 404. |
dimension_value | query | string | No | Optional dimension value to filter to. Only honored together with dimension_key; sent alone it is ignored and the unfiltered "Total" series is returned. |
Response fields
Fields returned in the 200 response body. Nested objects are listed under their parent. A field marked optional may be absent from the body; one marked nullable is always present but its value may be null.
| Field | Type | Description |
|---|---|---|
series | object[] | Time-series data as multiple series. |
key | string | Series key: 'total' for the unfiltered series, the dimension value for dimension series, or the end user ID when filtered by end_user_id. |
label | string | Series label for display. |
data_points | object[] | Data points for this series. |
date | string | Period date (ISO 8601). |
cost | string | Total cost for this period. |
event_count | number (double) | Number of events. |
granularity | daily | weekly | monthly | Granularity of the data. |
Error codes
Errors return the standard error envelope with a code, message, and a correlationId you can quote to support.
| Status | When it happens |
|---|---|
400 | Invalid request data. Ensure start_date and end_date are valid ISO 8601 dates and start_date is before end_date. |
401 | Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY. |
403 | API key lacks the costs:read scope. Create or update a key with the costs:read scope, then retry. |
404 | Dimension key not found for this organization. Verify dimension_key matches a dimension registered for your organization. |
429 | Rate limit exceeded. The general API tier allows 100 requests per 15 minutes; wait for the window to reset before retrying. |
Rate limits and retries
Rate limit exceeded. The general API tier allows 100 requests per 15 minutes; wait for the window to reset before retrying.