Cost Data API
Get cost summary
Returns the organization-wide total cost for the selected time window along with a comparison to the previous period, showing change amount and percentage to track cost trends. Call it with a GET request to /cost-data/summary, authenticated with a restricted API key and the "costs:read" scope.
Returns the organization-wide total cost for the selected time window along with a comparison to the previous period, showing change amount and percentage to track cost trends. For a single end user's summary, use GET /end-user-costs/{externalId}/summary instead. 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 |
|---|---|---|---|---|
time_window | query | current-period | last-period | last-7-days | last-30-days | last-90-days | ytd | last-year | No | Time window preset (default 'current-period' = the current calendar month to date; 'last-period' = the previous calendar month). |
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 |
|---|---|---|
current_period_cost | string | Current period total cost (USD, decimal string). |
previous_period_cost | string | Previous period total cost (USD, decimal string). |
change_amount | string | Change amount (current - previous, USD, decimal string). |
change_percent | number (double) nullable | Change percentage (null if previous is zero). |
period_start | string | Period start date (ISO 8601). |
period_end | string | Period end date (ISO 8601). |
event_count | number (double) optional | Number of events that contributed to current_period_cost (completed events in the window). Optional for backwards compatibility. |
status_counts | object optional | Org-wide event status breakdown for empty-state and pipeline-lag diagnosis. Optional for backwards compatibility. |
completed | number (double) | Events with completed cost calculation (contributing to current/previous period totals). |
pending | number (double) | Events still being processed by the cost-calculation worker. |
pending_rate_card | number (double) | Events accepted but waiting for a rate card to be configured for the model. |
failed | number (double) | Events that failed cost calculation. |
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 time_window. Use one of: current-period, last-period, last-7-days, last-30-days, last-90-days, ytd, last-year. |
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.