Cost Data API
Get organization-wide cost breakdown by provider
Returns organization-wide cost aggregation grouped by AI provider. Call it with a GET request to /cost-data/by-provider, authenticated with a restricted API key and the "costs:read" scope.
Returns organization-wide cost aggregation grouped by AI provider. provider_name reflects the provider string reported on your usage events when present (typically a lowercase slug such as 'openai'), otherwise the catalog display name. 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). |
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 |
|---|---|---|
providers | object[] | Cost breakdown by provider. |
provider_id | string | Provider ID (UUID); 'unknown' when the event could not be matched to a catalog provider. |
provider_slug | string | Provider slug. Uses the provider string reported on your usage events when present, otherwise the catalog slug; 'unknown' when unresolvable. |
provider_name | string | Provider name. Uses the provider string reported on your usage events when present, otherwise the catalog display name; 'Unknown' if unresolvable. |
total_cost | string | Total cost for this provider. |
event_count | number (double) | Number of events. |
percent_of_total | number (double) | Percentage of total organization cost. |
total_cost | string | Total cost across all providers. |
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. |
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.