Attribution Data API

Get cost breakdown by agent

Returns cost aggregation grouped by agent_id from usage event metadata. Call it with a GET request to /attribution-data/by-agent, authenticated with a restricted API key and the "costs:read" scope.

Returns cost aggregation grouped by agent_id from usage event metadata. Events without an agent_id are bucketed as "Unassigned". Convenience shortcut for GET /attribution-data/by-dimension with dimension=agent_id. Use by-dimension when you need cross-dimension filtering (filter_key/filter_value) or CSV export. 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).
`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 items.
`attribution_value`	`string`	Attribution value (e.g., agent name or workflow name).
`total_cost`	`string`	Total cost for this attribution value.
`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 the total cost within this query scope (date range plus any filter_key/filter_value filter). Values across items sum to 100.
`total_cost`	`string`	Total cost across all items.

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 start_date and end_date are valid ISO 8601 dates and fix the field named in error.message.
`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 an API key with the costs:read scope, then retry.
`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/attribution-data/by-agent

Response example

Success response (200):

{
  "items": [
    {
      "attribution_value": "quest-writer",
      "cache_creation_cost": null,
      "cache_creation_input_tokens": null,
      "cache_read_cost": null,
      "cache_read_input_tokens": null,
      "event_count": 3,
      "input_cost": "9.09",
      "input_tokens": 3636900,
      "output_cost": "4.59",
      "output_tokens": 459700,
      "percent_of_total": 40,
      "reasoning_cost": "2.32",
      "reasoning_tokens": 231900,
      "total_cost": "16"
    },
    {
      "attribution_value": "match-caster",
      "cache_creation_cost": "0.5",
      "cache_creation_input_tokens": 133400,
      "cache_read_cost": "0.18",
      "cache_read_input_tokens": 360750,
      "event_count": 6,
      "input_cost": "9.01",
      "input_tokens": 3603650,
      "output_cost": "4.31",
      "output_tokens": 429650,
      "percent_of_total": 35,
      "reasoning_cost": null,
      "reasoning_tokens": null,
      "total_cost": "14"
    },
    {
      "attribution_value": "npc-brain",
      "cache_creation_cost": null,
      "cache_creation_input_tokens": null,
      "cache_read_cost": "0.09",
      "cache_read_input_tokens": 181400,
      "event_count": 3,
      "input_cost": "5.31",
      "input_tokens": 2122500,
      "output_cost": "2.6",
      "output_tokens": 259350,
      "percent_of_total": 20,
      "reasoning_cost": null,
      "reasoning_tokens": null,
      "total_cost": "8"
    },
    {
      "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": "1.34",
      "input_tokens": 534900,
      "output_cost": "0.66",
      "output_tokens": 66200,
      "percent_of_total": 5,
      "reasoning_cost": null,
      "reasoning_tokens": null,
      "total_cost": "2"
    }
  ],
  "total_cost": "40"
}