Rate Cards API
Get the rate estimation table
Returns your organization's effective per-model rates in USD per million tokens, for client-side budget estimation; the server-side ledger is the record. Call it with a GET request to /rate-cards/estimation-table, authenticated with a restricted API key and the "costs:read" scope.
Returns your organization's effective per-model rates in USD per million tokens, for client-side budget estimation; the server-side ledger is the record. The Bear Lumen SDKs refresh their local price table from this endpoint at startup and use it to estimate span spend before each call, so budget caps can stop a runaway loop without waiting for the ledger. Treat the values as estimates only: the ledger prices each event with the rates in force at the event's own timestamp, so the two can diverge when rates change mid-run. Rates reflect your organization: when custom rates are agreed with Bear Lumen for a model, those replace the standard rates here. Cache and reasoning rates are already resolved to the same derived values the ledger applies, so you can multiply token counts by these rates directly. Models priced per unit rather than per token are not listed. Refresh once at process start (or at most hourly); rates change rarely. 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.
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 |
|---|---|---|
items | object[] | Effective per-model estimation rates for your organization, sorted by model_slug. Includes any organization-specific rates agreed with Bear Lumen in place of the standard rates. Models priced per unit rather than per token (e.g., audio or image generation) are not listed; estimate those from your own unit assumptions. |
model_slug | string | The model identifier rates apply to (e.g., "gpt-4o", "claude-sonnet-4-5"). Match your call's model name against these slugs by longest prefix, the same rule the cost ledger uses (e.g., "gpt-4o-2024-05-13" matches "gpt-4o"). |
input_cost_per_million | string | Cost per million input tokens (USD, decimal string). |
cache_creation_cost_per_million | string nullable | Cost per million cache-creation input tokens (USD, decimal string). Already resolved: when the model has no explicit cache-creation rate, this carries the same derived rate the cost ledger applies. A null means the token class cannot be priced for this model; treat those tokens as unpriced in estimates. |
cache_read_cost_per_million | string nullable | Cost per million cache-read input tokens (USD, decimal string). Resolved the same way as cache_creation_cost_per_million; null means the token class cannot be priced for this model. |
output_cost_per_million | string | Cost per million output tokens (USD, decimal string). |
reasoning_cost_per_million | string nullable | Cost per million reasoning tokens (USD, decimal string). Already resolved: models without an explicit reasoning rate carry the output rate here, matching the cost ledger. A null means the token class cannot be priced for this model. |
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 | Missing or invalid API key. Send your key as Authorization: Bearer YOUR_API_KEY. |
403 | API key lacks the costs:read scope. Create or update an API key with the costs:read scope, then retry. |
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.