Cost Data API

Get organization-wide cost trend

Returns organization-wide time-series cost data. Call it with a GET request to /cost-data/trend, authenticated with a restricted API key and the "costs:read" scope.

GET https://api.bearlumen.com/v1/cost-data/trend

Returns organization-wide time-series cost data. Can be filtered to one end user, filtered to one dimension value, or grouped by dimension. **Granularity** (not overridable): ranges up to 30 days return daily points, 31 to 90 days weekly, over 90 days monthly. **Modes:** - No filter params: Returns a single "Total" series (all costs) - `dimension_key` only: Returns top 5 dimension values as series + "Other" - `dimension_key` + `dimension_value`: Returns a single series filtered to that value - `end_user_id`: Returns a single series for that end user `dimension_key` must be a dimension registered for your organization; unknown keys return 404. `dimension_value` is only honored together with `dimension_key`; if sent alone the parameter is ignored and the unfiltered "Total" series is returned. If `dimension_key` or `dimension_value` is provided, `end_user_id` is ignored; do not combine them. 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).
`end_user_id`	query	`string`	No	Optional end user ID (UUID, as returned in /cost-data/by-end-user end_user_id) to filter the trend to one end user. Must be a UUID; the 'unassigned' bucket cannot be filtered here. Prefer GET /end-user-costs/{externalId}/trend for per-end-user analysis.
`dimension_key`	query	`string`	No	Optional dimension key to filter or group by. Must be a dimension registered for your organization; unknown keys return 404.
`dimension_value`	query	`string`	No	Optional dimension value to filter to. Only honored together with dimension_key; sent alone it is ignored and the unfiltered "Total" series is returned.

Response example

Success response (200):

{
  "granularity": "daily",
  "series": [
    {
      "data_points": [
        {
          "cost": "612.44",
          "date": "2026-01-04T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "12.07",
          "date": "2026-01-05T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "16.32",
          "date": "2026-01-08T00:00:00.000Z",
          "event_count": 2
        },
        {
          "cost": "484.72",
          "date": "2026-01-09T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "9.37",
          "date": "2026-01-12T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "173.58",
          "date": "2026-01-13T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "390.2",
          "date": "2026-01-15T00:00:00.000Z",
          "event_count": 2
        },
        {
          "cost": "96.13",
          "date": "2026-01-17T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "10.53",
          "date": "2026-01-19T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "274.98",
          "date": "2026-01-21T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "43.6",
          "date": "2026-01-22T00:00:00.000Z",
          "event_count": 2
        },
        {
          "cost": "58.27",
          "date": "2026-01-26T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "0.48",
          "date": "2026-01-27T00:00:00.000Z",
          "event_count": 1
        }
      ],
      "key": "total",
      "label": "Total"
    }
  ]
}

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.
`404`	Dimension key not found for this organization. Verify dimension_key matches a dimension registered for your organization.
`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.