Cost Data API

Get organization-wide cost breakdown by model

Returns organization-wide cost aggregation grouped by AI model (gpt-4o, claude-3-5-sonnet, etc.). Call it with a GET request to /cost-data/by-model, authenticated with a restricted API key and the "costs:read" scope.

Returns organization-wide cost aggregation grouped by AI model (gpt-4o, claude-3-5-sonnet, etc.). All models are returned (no truncation), so entries always sum to total_cost. 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
`models`	`object[]`	Cost breakdown by model.
`model_slug`	`string`	Model slug.
`provider_slug`	`string`	Provider slug; 'unknown' when the model could not be matched to a catalog provider.
`total_cost`	`string`	Total cost for this model.
`input_tokens`	`number (double)`	Input tokens used.
`output_tokens`	`number (double)`	Output tokens used.
`cache_creation_input_tokens`	`number (double)` nullable	Cache-creation input tokens; null = provider did not report.
`cache_read_input_tokens`	`number (double)` nullable	Cache-read input tokens; null = provider did not report.
`reasoning_tokens`	`number (double)` nullable	Reasoning tokens; null = not reported.
`input_cost`	`string`	Input cost (USD, decimal string).
`output_cost`	`string`	Output cost (USD, decimal string).
`cache_creation_cost`	`string` nullable	Cache-creation cost (USD string); null = not reported.
`cache_read_cost`	`string` nullable	Cache-read cost (USD string); null = not reported.
`reasoning_cost`	`string` nullable	Reasoning cost (USD string); null = not reported.
`event_count`	`number (double)`	Number of events.
`percent_of_total`	`number (double)`	Percentage of total organization cost.
`total_cost`	`string`	Total cost across all models.

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.

GEThttps://api.bearlumen.com/v1/cost-data/by-model

Response example

Success response (200):

{
  "models": [
    {
      "cache_creation_cost": null,
      "cache_creation_input_tokens": null,
      "cache_read_cost": null,
      "cache_read_input_tokens": null,
      "event_count": 5,
      "input_cost": "797.87",
      "input_tokens": 6780600,
      "model_slug": "gpt-4o",
      "output_cost": "399.2",
      "output_tokens": 1016600,
      "percent_of_total": 54.84379366744705,
      "provider_slug": "unknown",
      "reasoning_cost": null,
      "reasoning_tokens": null,
      "total_cost": "1197.07"
    },
    {
      "cache_creation_cost": null,
      "cache_creation_input_tokens": null,
      "cache_read_cost": null,
      "cache_read_input_tokens": null,
      "event_count": 3,
      "input_cost": "545.32",
      "input_tokens": 794200,
      "model_slug": "claude-3-5-sonnet",
      "output_cost": "272.65",
      "output_tokens": 198500,
      "percent_of_total": 37.47531715452034,
      "provider_slug": "unknown",
      "reasoning_cost": null,
      "reasoning_tokens": null,
      "total_cost": "817.97"
    },
    {
      "cache_creation_cost": null,
      "cache_creation_input_tokens": null,
      "cache_read_cost": null,
      "cache_read_input_tokens": null,
      "event_count": 3,
      "input_cost": "64.7",
      "input_tokens": 6238400,
      "model_slug": "gemini-2.0-flash",
      "output_cost": "32.5",
      "output_tokens": 1239100,
      "percent_of_total": 4.453220567281657,
      "provider_slug": "unknown",
      "reasoning_cost": null,
      "reasoning_tokens": null,
      "total_cost": "97.2"
    },
    {
      "cache_creation_cost": null,
      "cache_creation_input_tokens": null,
      "cache_read_cost": null,
      "cache_read_input_tokens": null,
      "event_count": 3,
      "input_cost": "29.8",
      "input_tokens": 11236700,
      "model_slug": "gpt-4o-mini",
      "output_cost": "15.62",
      "output_tokens": 2633200,
      "percent_of_total": 2.080918499649515,
      "provider_slug": "unknown",
      "reasoning_cost": null,
      "reasoning_tokens": null,
      "total_cost": "45.42"
    },
    {
      "cache_creation_cost": "1.36",
      "cache_creation_input_tokens": 361000,
      "cache_read_cost": "0.69",
      "cache_read_input_tokens": 2300000,
      "event_count": 2,
      "input_cost": "9.41",
      "input_tokens": 3133100,
      "model_slug": "claude-sonnet-4",
      "output_cost": "13.57",
      "output_tokens": 903500,
      "percent_of_total": 1.146750111101439,
      "provider_slug": "unknown",
      "reasoning_cost": null,
      "reasoning_tokens": null,
      "total_cost": "25.03"
    }
  ],
  "total_cost": "2182.69"
}