End User Costs API

Get cost breakdown by dimension for a specific end-user

Returns cost aggregation grouped by a metadata dimension key for the specified end-user. Call it with a GET request to /end-user-costs/{externalId}/by-dimension, authenticated with a restricted API key and the "costs:read" scope.

Returns cost aggregation grouped by a metadata dimension key for the specified end-user. Events that do not carry the requested key are grouped under the literal value "Unassigned". A key that no events carry does not return an error; it returns the full cost in a single "Unassigned" row, so verify the key name if you see 100% Unassigned. 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
`externalId`	path	`string`	Yes	End-user identifier you assigned when sending usage events (the user_id field on POST /usage-events). An end user exists only after at least one event referencing this identifier has been ingested; unknown identifiers return 404.
`dimension`	query	`string`	Yes	Metadata dimension key to group by (e.g., 'feature', 'team', 'agent_id'). Only 'feature' reads a typed event field; every other key is looked up in event metadata. For per-model or per-provider breakdowns use the dedicated /by-model and /by-provider endpoints instead of a metadata key.
`start_date`	query	`string`	Yes	Start of date range (ISO 8601, inclusive).
`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_user_id`	`string`	Bear Lumen internal end-user ID (UUID). Use the externalId path parameter for lookups, not this value.
`items`	`object[]`	Cost breakdown by dimension value.
`attribution_value`	`string`	Dimension value; events missing the requested metadata key are grouped under the literal value 'Unassigned'.
`total_cost`	`string`	Total cost for this dimension value (decimal string).
`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 end-user's total cost for this dimension.
`total_cost`	`string`	Total cost across all dimension values (decimal string).

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. Check that required query parameters are present and that start_date and end_date are valid ISO 8601 dates.
`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.
`404`	End user not found. The identifier must match the user_id value sent on at least one ingested usage event.
`429`	Rate limit exceeded. Retry after the time indicated by the Retry-After header (rate-limit state is also reported in the standard RateLimit-* headers, e.g. RateLimit-Reset).

Rate limits and retries

Rate limit exceeded. Retry after the time indicated by the Retry-After header (rate-limit state is also reported in the standard RateLimit-* headers, e.g. RateLimit-Reset).

GEThttps://api.bearlumen.com/v1/end-user-costs/{externalId}/by-dimension

Response example

Success response (200):

{
  "end_user_id": "eb77aa11-0001-7777-9a1b-2c3d4e5f6a01",
  "items": [
    {
      "attribution_value": "chat-completion",
      "cache_creation_cost": "1.86",
      "cache_creation_input_tokens": 88400,
      "cache_read_cost": "1.21",
      "cache_read_input_tokens": 403200,
      "event_count": 2,
      "input_cost": "570.64",
      "input_tokens": 821000,
      "output_cost": "285.07",
      "output_tokens": 205700,
      "percent_of_total": 45,
      "reasoning_cost": null,
      "reasoning_tokens": null,
      "total_cost": "858.78"
    },
    {
      "attribution_value": "summarization",
      "cache_creation_cost": null,
      "cache_creation_input_tokens": null,
      "cache_read_cost": null,
      "cache_read_input_tokens": null,
      "event_count": 3,
      "input_cost": "445.3",
      "input_tokens": 1346500,
      "output_cost": "222.64",
      "output_tokens": 336600,
      "percent_of_total": 35,
      "reasoning_cost": null,
      "reasoning_tokens": null,
      "total_cost": "667.94"
    },
    {
      "attribution_value": "Unassigned",
      "cache_creation_cost": null,
      "cache_creation_input_tokens": null,
      "cache_read_cost": null,
      "cache_read_input_tokens": null,
      "event_count": 1,
      "input_cost": "254.45",
      "input_tokens": 1183100,
      "output_cost": "127.23",
      "output_tokens": 295800,
      "percent_of_total": 20,
      "reasoning_cost": null,
      "reasoning_tokens": null,
      "total_cost": "381.68"
    }
  ],
  "total_cost": "1908.4"
}