Attribution Data API

Get attribution time-series

Returns time-bucketed multi-series cost data grouped by any metadata dimension key. Call it with a GET request to /attribution-data/time-series, authenticated with a restricted API key and the "costs:read" scope.

GET https://api.bearlumen.com/v1/attribution-data/time-series

Returns time-bucketed multi-series cost data grouped by any metadata dimension key. Granularity is chosen from the date range: daily for ranges up to 30 days, weekly up to 90 days, monthly beyond. The five highest-cost dimension values each get their own series; when more than five values exist, the remaining values are aggregated into an extra series with key "other" and label "Other". 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`	query	`string`	Yes	Metadata dimension key to group by (e.g., "model", "provider", "agent_id").
`start_date`	query	`string`	Yes	Start of date range (ISO 8601, inclusive).
`end_date`	query	`string`	Yes	End of date range (ISO 8601, exclusive).
`filter_key`	query	`string`	No	Optional cross-dimension filter key (e.g., "environment"). Applied only when filter_value is also provided; a request with filter_key alone returns the unfiltered series.
`filter_value`	query	`string`	No	Optional cross-dimension filter value (exact match). Applied only when filter_key is also provided; a request with filter_value alone returns the unfiltered series.

Response example

Success response (200):

{
  "granularity": "daily",
  "series": [
    {
      "data_points": [
        {
          "date": "2026-02-05T00:00:00.000Z",
          "event_count": 1,
          "total_cost": "3.02"
        },
        {
          "date": "2026-02-06T00:00:00.000Z",
          "event_count": 1,
          "total_cost": "4.78"
        },
        {
          "date": "2026-02-07T00:00:00.000Z",
          "event_count": 1,
          "total_cost": "8.2"
        }
      ],
      "key": "quest-generation",
      "label": "quest-generation"
    },
    {
      "data_points": [
        {
          "date": "2026-02-03T00:00:00.000Z",
          "event_count": 2,
          "total_cost": "6.34"
        },
        {
          "date": "2026-02-04T00:00:00.000Z",
          "event_count": 1,
          "total_cost": "2.16"
        }
      ],
      "key": "match-narration",
      "label": "match-narration"
    },
    {
      "data_points": [
        {
          "date": "2026-02-03T00:00:00.000Z",
          "event_count": 1,
          "total_cost": "2.66"
        },
        {
          "date": "2026-02-04T00:00:00.000Z",
          "event_count": 1,
          "total_cost": "2.44"
        },
        {
          "date": "2026-02-05T00:00:00.000Z",
          "event_count": 1,
          "total_cost": "2.9"
        }
      ],
      "key": "npc-dialogue",
      "label": "npc-dialogue"
    },
    {
      "data_points": [
        {
          "date": "2026-02-03T00:00:00.000Z",
          "event_count": 1,
          "total_cost": "1.4"
        },
        {
          "date": "2026-02-04T00:00:00.000Z",
          "event_count": 1,
          "total_cost": "2"
        },
        {
          "date": "2026-02-06T00:00:00.000Z",
          "event_count": 1,
          "total_cost": "2.1"
        },
        {
          "date": "2026-02-07T00:00:00.000Z",
          "event_count": 1,
          "total_cost": "2"
        }
      ],
      "key": "world-summary",
      "label": "world-summary"
    }
  ]
}

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.