Dimension Data API

Get cost breakdown by dimension

Returns cost aggregated by a specific custom dimension (e.g., "team", "region"). Call it with a GET request to /dimension-data/cost-breakdown, authenticated with a restricted API key and the "costs:read" scope.

Returns cost aggregated by a specific custom dimension (e.g., "team", "region"). Groups costs by the dimension values (e.g., "team-ml", "team-api"). Events that do not carry the dimension key in their metadata are grouped under the reserved dimensionValue "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
`dimension_key`	query	`string`	Yes	Dimension key exactly as returned by GET /dimension-data/definitions (snake_case, case-sensitive).
`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
`items`	`object[]`	Cost breakdown by dimension value.
`dimension_value`	`string`	Dimension value (e.g., "team-ml", "region-us-east"). Events missing this dimension key in their metadata are grouped as "Unassigned".
`total_cost`	`string`	Total cost for this dimension value (USD, decimal string).
`input_tokens`	`number (double)`	Input tokens used.
`output_tokens`	`number (double)`	Output tokens used.
`event_count`	`number (double)`	Number of events.
`percent_of_total`	`number (double)`	Percentage of total organization cost.
`total_cost`	`string`	Total cost across all dimension values (USD, 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. Check that start_date and end_date are valid ISO 8601 dates.
`401`	Authentication required. Provide a valid API key in the Authorization header.
`403`	Insufficient permissions. Use an API key with the costs:read scope.
`404`	Dimension not found. Pass a dimension_key exactly as returned by GET /dimension-data/definitions (snake_case, case-sensitive).
`429`	Rate limit or plan quota exceeded. Slow down and retry after the current window resets.

Rate limits and retries

Rate limit or plan quota exceeded. Slow down and retry after the current window resets.

GEThttps://api.bearlumen.com/v1/dimension-data/cost-breakdown

Response example

Success response (200):

{
  "items": [
    {
      "dimension_value": "production",
      "event_count": 4,
      "input_tokens": 1712800,
      "output_tokens": 428100,
      "percent_of_total": 80.71462278198004,
      "total_cost": "1761.75"
    },
    {
      "dimension_value": "staging",
      "event_count": 2,
      "input_tokens": 457300,
      "output_tokens": 114300,
      "percent_of_total": 12.35677077367835,
      "total_cost": "269.71"
    },
    {
      "dimension_value": "Unassigned",
      "event_count": 9,
      "input_tokens": 25880200,
      "output_tokens": 5415300,
      "percent_of_total": 4.995670480004032,
      "total_cost": "109.04"
    },
    {
      "dimension_value": "development",
      "event_count": 1,
      "input_tokens": 132700,
      "output_tokens": 33200,
      "percent_of_total": 1.9329359643375834,
      "total_cost": "42.19"
    }
  ],
  "total_cost": "2182.69"
}