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.

GET https://api.bearlumen.com/v1/cost-data/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. 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 example

Success response (200):

{
  "change_amount": "843.674",
  "change_percent": 25,
  "current_period_cost": "4218.37",
  "event_count": 3,
  "period_end": "2026-01-21T16:45:00.000Z",
  "period_start": "2026-01-01T00:00:00.000Z",
  "previous_period_cost": "3374.696",
  "status_counts": {
    "completed": 64,
    "failed": 0,
    "pending": 0,
    "pending_rate_card": 0
  }
}

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.