Dimension Data API
Get numeric dimension summary
Returns a single aggregated numeric value (SUM/AVG/MIN/MAX) for a numeric custom dimension. Call it with a GET request to /dimension-data/numeric-summary, authenticated with a restricted API key and the "costs:read" scope.
Returns a single aggregated numeric value (SUM/AVG/MIN/MAX) for a numeric custom dimension. Only works with dimensions of value_type 'number'. 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). |
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 |
|---|---|---|
value | string nullable | Aggregated numeric value as string, or null when no events match. |
event_count | number (double) | Number of events with a non-null value for this dimension. |
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, 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.