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.
GET https://api.bearlumen.com/v1/dimension-data/definitions
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 example
Success response (200):
{
"dimensions": [
{
"created_at": "2026-01-05T09:12:00.000Z",
"description": "Deployment environment that generated the AI usage",
"id": "dd88c1a2-0001-8888-9a1b-2c3d4e5f6a01",
"is_required": false,
"key": "environment",
"name": "Environment",
"organization_id": "b7e6a3f2-4c1d-4e8a-9b5f-2d7c8e1a6f43",
"value_type": "string"
},
{
"created_at": "2026-01-08T14:30:00.000Z",
"description": "Number of documents processed per pipeline batch",
"id": "dd88c1a2-0002-8888-9a1b-2c3d4e5f6a02",
"is_required": false,
"key": "batch_size",
"name": "Batch Size",
"organization_id": "b7e6a3f2-4c1d-4e8a-9b5f-2d7c8e1a6f43",
"value_type": "number"
}
],
"total": 2
}
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.