Cost Data API

Get organization-wide cost breakdown by end user

Returns organization-wide cost aggregation grouped by end user (your customers). Call it with a GET request to /cost-data/by-end-user, authenticated with a restricted API key and the "costs:read" scope.

Returns organization-wide cost aggregation grouped by end user (your customers). Events without an end user are bucketed as "Unassigned". All end users are returned (no truncation), so entries always sum to total_cost. Each end_user_id is Bear Lumen's internal end-user UUID (or the literal 'unassigned'), not the external_id you supplied on usage events. Use this endpoint to rank spend across all of your end users. For a per-end-user drill-down (per-model, per-provider, trend, per-dimension), use the End User Costs API endpoints under /end-user-costs/{externalId}, which are addressed by the external_id you supplied on usage events. 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
`end_users`	`object[]`	Cost breakdown by end user.
`end_user_id`	`string`	End user ID (UUID). 'unassigned' when events carry no end user. Note: this is Bear Lumen's internal end-user ID, not the external_id you supplied on usage events.
`end_user_name`	`string`	End user display name.
`total_cost`	`string`	Total cost for this end user.
`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 end users.

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-end-user

Response example

Success response (200):

{
  "end_users": [
    {
      "cache_creation_cost": "0.53",
      "cache_creation_input_tokens": 141000,
      "cache_read_cost": "0.27",
      "cache_read_input_tokens": 890000,
      "end_user_id": "unassigned",
      "end_user_name": "Unassigned",
      "event_count": 10,
      "input_cost": "1425.26",
      "input_tokens": 6193200,
      "output_cost": "716.87",
      "output_tokens": 1503600,
      "percent_of_total": 98.17839454984446,
      "reasoning_cost": null,
      "reasoning_tokens": null,
      "total_cost": "2142.93"
    },
    {
      "cache_creation_cost": "0.83",
      "cache_creation_input_tokens": 220000,
      "cache_read_cost": "0.42",
      "cache_read_input_tokens": 1410000,
      "end_user_id": "ea1b2c3d-9999-4e4f-9a5b-6c7d8e9f0a01",
      "end_user_name": "Northwind Robotics",
      "event_count": 3,
      "input_cost": "14.59",
      "input_tokens": 11304700,
      "output_cost": "12.55",
      "output_tokens": 2394100,
      "percent_of_total": 1.3006885998469777,
      "reasoning_cost": null,
      "reasoning_tokens": null,
      "total_cost": "28.39"
    },
    {
      "cache_creation_cost": null,
      "cache_creation_input_tokens": null,
      "cache_read_cost": null,
      "cache_read_input_tokens": null,
      "end_user_id": "ea1b2c3d-9999-4e4f-9a5b-6c7d8e9f0a02",
      "end_user_name": "Cascade Analytics",
      "event_count": 3,
      "input_cost": "7.25",
      "input_tokens": 10685100,
      "output_cost": "4.12",
      "output_tokens": 2093200,
      "percent_of_total": 0.5209168503085642,
      "reasoning_cost": null,
      "reasoning_tokens": null,
      "total_cost": "11.37"
    }
  ],
  "total_cost": "2182.69"
}