Dimension Data API

Get cost trend by dimension

Returns time-series cost data with adaptive granularity based on date range. Call it with a GET request to /dimension-data/cost-trend, authenticated with a restricted API key and the "costs:read" scope.

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

Returns time-series cost data with adaptive granularity based on date range. Can filter by specific dimension value or group by dimension. Adaptive granularity: date ranges of 30 days or less return daily buckets, 31-90 days return weekly, and longer ranges return monthly. Granularity cannot be overridden on this endpoint; only `/dimension-data/numeric-trend` accepts an `interval` parameter. The response `granularity` field reports which bucket size was used. **Modes:** - No dimension params: Returns single "Total" series (all costs) - `dimension_key` only: Returns top 5 dimension values as series + "Other" - `dimension_key` + `dimension_value`: Returns single series filtered by that value When grouping by `dimension_key`, events that do not carry the dimension key in their metadata are grouped under the reserved value "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
`start_date`	query	`string`	Yes	Start of date range (ISO 8601, inclusive).
`end_date`	query	`string`	Yes	End of date range (ISO 8601, exclusive).
`dimension_key`	query	`string`	No	Optional dimension key to filter/group by, exactly as returned by GET /dimension-data/definitions (snake_case, case-sensitive).
`dimension_value`	query	`string`	No	Optional specific dimension value to filter to.

Response example

Success response (200):

{
  "granularity": "daily",
  "series": [
    {
      "data_points": [
        {
          "cost": "612.44",
          "date": "2026-01-04T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "484.72",
          "date": "2026-01-09T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "389.61",
          "date": "2026-01-15T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "274.98",
          "date": "2026-01-21T00:00:00.000Z",
          "event_count": 1
        }
      ],
      "key": "production",
      "label": "production"
    },
    {
      "data_points": [
        {
          "cost": "173.58",
          "date": "2026-01-13T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "96.13",
          "date": "2026-01-17T00:00:00.000Z",
          "event_count": 1
        }
      ],
      "key": "staging",
      "label": "staging"
    },
    {
      "data_points": [
        {
          "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": "9.37",
          "date": "2026-01-12T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "0.59",
          "date": "2026-01-15T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "10.53",
          "date": "2026-01-19T00:00:00.000Z",
          "event_count": 1
        },
        {
          "cost": "1.41",
          "date": "2026-01-22T00:00:00.000Z",
          "event_count": 1
        },
        {
          "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": "Unassigned",
      "label": "Unassigned"
    },
    {
      "data_points": [
        {
          "cost": "42.19",
          "date": "2026-01-22T00:00:00.000Z",
          "event_count": 1
        }
      ],
      "key": "development",
      "label": "development"
    }
  ]
}

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.