Usage
GET /v1/usage — aggregated usage and provisional cost.
GET https://api.inference.runatlas.com/v1/usageAuthenticated with a read-scoped key (atl_read_) or a console session. An
inference key is not accepted.
curl "https://api.inference.runatlas.com/v1/usage?group_by=model,api_key,time&bucket=day" \
-H "Authorization: Bearer $ATLAS_READ_KEY"Query parameters
startstringISO 8601 timestamp, or a bare date (2026-09-01) meaning the start of that
UTC day. Defaults to the start of the current UTC month.
endstringExclusive. Defaults to the start of the next UTC month.
modelstringOne model identifier.
api_key_idstringOne key, by its id (a UUID, not the prefix).
group_bystringdefault: modelComma-separated, any of model, api_key, time. All requested breakdowns
are returned from the one call — three round trips would be three scans of the
same partition.
bucketstringdefault: dayhour or day. Applies to the time breakdown.
A period may span at most 93 days.
Response
{
"organization_id": "...",
"period": { "start": "2026-09-01T00:00:00.000Z", "end": "2026-10-01T00:00:00.000Z", "bucket": "day" },
"filters": { "model": null, "api_key_id": null },
"requests": 18422,
"tokens": {
"backend_reported_input": 5218440,
"backend_reported_output": 1044210,
"backend_reported_reasoning": 0,
"generated_output": 1044210,
"delivered_output": 1041902,
"atlas_counted_input": 261200,
"atlas_counted_output": 52180,
"atlas_counted_requests": 920
},
"cost": { "input": "2.60922", "output": "1.56631", "total": "4.17553", "currency": "USD", "provisional": true },
"breakdowns": {
"model": [{ "key": { "model_identifier": "atlas-mid-1", "model_id": "..." }, "requests": 14200, "tokens": {}, "cost": {} }],
"api_key": [{ "key": { "api_key_id": "8f2c1d5e-...", "api_key_label": "production", "api_key_prefix": "atl_live_9f1c0f6e" }, "requests": 9100, "tokens": {}, "cost": {} }],
"time": [{ "key": { "bucket_start": "2026-09-08T00:00:00.000Z" }, "requests": 640, "tokens": {}, "cost": {} }]
},
"throttled": {
"source": "rejection_counters",
"total": 37,
"by_limit_scope": [{ "limit_scope": "tokens", "model_identifier": "atlas-mid-1", "count": 37 }]
},
"pricing": { "provisional": true, "billing_enabled": false, "reasoning_tokens_billed_as": "output", "reasoning_tokens_included_in_output": true },
"cost_units": { "decimals": 14, "basis": "price_per_million_tokens_stamped_on_row" }
}Breakdown keys
api_key_label / api_key_prefixstring | nullThe key's label and its non-secret prefix — the same two facts the console
lists a key by. Both are null for the unattributed group, which has no key,
and for a key that no longer belongs to this organization. api_key_id is
what the api_key_id filter takes; the label is what a person reads.
Token fields
backend_reported_input / backend_reported_outputintegerThe meter of record. These are the figures cost is computed from.
backend_reported_reasoningintegerAlready counted inside backend_reported_output. Never add them.
generated_output / delivered_outputintegerProduced by the model, versus reaching the client. They diverge on a disconnect. Neither is derivable from the other, which is why both are stored.
atlas_counted_input / atlas_counted_outputintegerAtlas's independent count over a sampled fraction only, sized by
atlas_counted_requests. A metering-accuracy check, not a billing figure.
Cost
Projected from the price stamped on each usage row at the time it was written, never from the current published price. Values are decimal strings with 14 places; round for display, not for storage.
If the period mixes currencies, cost is null and mixed_currency: true is
set rather than summing incomparable figures.
Throttling
Rate-limited requests write no usage row, so these figures come from admission counters — recent and approximate, where the metered figures are durable and exact.
"source": "unavailable" with "total": null means no counter source is
wired, not that nothing was throttled.
Errors
| Status | Code | |
|---|---|---|
| 400 | invalid_query | A parameter failed validation. |
| 400 | period_inverted | end at or before start. |
| 400 | period_too_long | More than 93 days. |
| 401 | — | Missing, invalid, or wrong-scope key. |
Row-level data
For one row per request rather than aggregates, use
GET /v1/usage/export.