Dimension Data API

Get numeric dimension trend

Returns time-bucketed aggregated numeric values (SUM/AVG/MIN/MAX) for a numeric custom dimension. Call it with a GET request to /dimension-data/numeric-trend, authenticated with a restricted API key and the "costs:read" scope.

Returns time-bucketed aggregated numeric values (SUM/AVG/MIN/MAX) for a numeric custom dimension. Granularity is adaptive based on date range, or can be specified explicitly via interval. Only works with dimensions of value_type 'number'. Adaptive granularity: date ranges of 30 days or less return daily buckets, 31-90 days return weekly, and longer ranges return monthly. Pass `interval` to override. The response `granularity` field reports which bucket size was used. 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	Numeric dimension key to aggregate, exactly as returned by GET /dimension-data/definitions (snake_case, case-sensitive).
`aggregation`	query	`sum` \| `avg` \| `min` \| `max`	Yes	Aggregation function (sum, avg, min, max).
`start_date`	query	`string`	Yes	Start of date range (ISO 8601, inclusive).
`end_date`	query	`string`	Yes	End of date range (ISO 8601, exclusive).
`interval`	query	`daily` \| `weekly` \| `monthly`	No	Optional granularity override (daily, weekly, monthly).

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
`data_points`	`object[]`	Time-bucketed aggregated numeric values.
`date`	`string`	Period date (ISO 8601).
`value`	`string` nullable	Aggregated numeric value as string, or null when no events in this period.
`event_count`	`number (double)`	Number of events in this period.
`granularity`	`daily` \| `weekly` \| `monthly`	Granularity of the data.
`aggregation`	`string`	Aggregation function used. One of: 'sum', 'avg', 'min', 'max'.
`dimension_key`	`string`	Dimension key that was aggregated.

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 date formats, use an aggregation of sum, avg, min, or max, an interval of daily, weekly, or monthly, and target a dimension with value_type "number".
`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/numeric-trend

Response example

Success response (200):

{
  "aggregation": "sum",
  "data_points": [
    {
      "date": "2025-12-29T00:00:00.000Z",
      "event_count": 1,
      "value": "128"
    },
    {
      "date": "2026-01-05T00:00:00.000Z",
      "event_count": 1,
      "value": "256"
    },
    {
      "date": "2026-01-12T00:00:00.000Z",
      "event_count": 3,
      "value": "272"
    },
    {
      "date": "2026-01-19T00:00:00.000Z",
      "event_count": 2,
      "value": "224"
    },
    {
      "date": "2026-01-26T00:00:00.000Z",
      "event_count": 1,
      "value": "48"
    }
  ],
  "dimension_key": "batch_size",
  "granularity": "weekly"
}