Dimension Data API
Get dimension definitions
Returns all dimension definitions for the organization. Call it with a GET request to /dimension-data/definitions, authenticated with a restricted API key and the "dimensions:read" scope.
Returns all dimension definitions for the organization. Dimensions define the metadata keys that can be used to filter and group costs. Dimension values are supplied through the `metadata` object on usage events sent to `POST /usage-events`. Dimensions marked `isRequired` are enforced at ingestion: events missing the key are rejected. Numeric dimensions (`value_type` "number") require a finite JSON number value and can be aggregated via `/dimension-data/numeric-summary` and `/dimension-data/numeric-trend`. 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 dimensions:read scope.
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 |
|---|---|---|
dimensions | object[] | List of dimension definitions. |
id | string | Dimension ID (UUID). |
organization_id | string | Organization ID (UUID). |
name | string | Display name. |
key | string | Metadata key. |
description | string optional | Optional description. |
value_type | string | number | Value type of the dimension: 'string' or 'number'. Dimensions with value_type 'number' can be aggregated via /dimension-data/numeric-summary and /dimension-data/numeric-trend. |
is_required | boolean | When true, usage events missing this metadata key are rejected at ingestion. |
created_at | string | Creation timestamp (ISO 8601). |
total | number (double) | Total count. |
Error codes
Errors return the standard error envelope with a code, message, and a correlationId you can quote to support.
| Status | When it happens |
|---|---|
401 | Authentication required. Provide a valid API key in the Authorization header. |
403 | Insufficient permissions. Use an API key with the dimensions:read scope. |
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.