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.

GET https://api.bearlumen.com/v1/cost-data/by-provider

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 example

Success response (200):

{
  "providers": [
    {
      "event_count": 8,
      "percent_of_total": 56.924712167096565,
      "provider_id": "unknown",
      "provider_name": "openai",
      "provider_slug": "openai",
      "total_cost": "1242.49"
    },
    {
      "event_count": 5,
      "percent_of_total": 38.62206726562178,
      "provider_id": "unknown",
      "provider_name": "anthropic",
      "provider_slug": "anthropic",
      "total_cost": "843"
    },
    {
      "event_count": 3,
      "percent_of_total": 4.453220567281657,
      "provider_id": "unknown",
      "provider_name": "google",
      "provider_slug": "google",
      "total_cost": "97.2"
    }
  ],
  "total_cost": "2182.69"
}

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.