Usage
List usage logs ordered by timestamp (most recent first).
Supports optional filters for time range, user, status, failure status code, model, endpoint, provider, source, session (source_label), and request group (request_group_id, repeatable, which returns a routed request's whole attempt plan). Paginated via skip/limit. The return shape is a bare JSON array; external billing/analytics consumers depend on this, so the total row count for a paginated UI is served separately by GET /api/v1/usage/count rather than wrapped in an envelope here. Timestamps accept either ISO 8601 strings or Unix epoch seconds (numeric).
Enter your API key here (sent as Otari-Key header).
Return logs with timestamp >= start_date (ISO 8601 or Unix epoch seconds)
Return logs with timestamp < end_date (ISO 8601 or Unix epoch seconds)
Filter to one or more users; repeatable (user_id=a&user_id=b). Several values match any of them. At most 50 per call.
Filter to a single status: 'success', 'error', or 'absorbed' (an attempt a routing policy recovered from, excluded from error_count and request_count)
Filter to a single failure status code (e.g. 429 for provider rate limits, 402 for missing-pricing rejections). Only error rows carry one, so this filter also restricts to status='error' unless 'status' is given explicitly
Filter to one or more models; repeatable (model=a&model=b). Several values match any of them. At most 50 per call.
Filter to a single endpoint (e.g. '/v1/chat/completions')
Filter to a single provider (e.g. 'openai')
Filter to a single provenance source (e.g. 'gateway' or 'claude_code')
Filter to a single session (source_label): the session's trace id on a gateway request that named one, or the session/project label imported usage carried
Filter by a request tag (what a request sent in its metadata), as key:value. Repeatable: values for the same key match any of them, and different keys must all match. At most 50 per call.
Filter to one or more API key ids; repeatable (api_key_id=a&api_key_id=b). Several values match any of them. At most 50 per call.
Filter by token-pricing state: true = only rows whose model tokens were priced, false = only rows that still need pricing (no cost at all, or tokens that were never metered because the model had no rate). A row charged only for gateway-run tool calls still counts as needing pricing.
Filter to requests that ran a gateway-run tool. 'any' matches any tool; a tool name (web_search, web_fetch, code_execution) matches that tool specifically.
Filter by budget participation, which is not the same question as provenance: true = only enforced gateway rows, false = every row that never touches a budget, meaning imported usage and also gateway traffic on a budget-exempt key
Filter to the rows of one or more request groups; repeatable (request_group_id=a&request_group_id=b). A routed request writes one row per attempt, all sharing a request_group_id, so this returns a request's whole plan: its absorbed attempts and the attempt that served it. Ignore ordering by timestamp and read attempt_position to reconstruct the plan. At most 1000 ids per call.
Only usage recorded in this workspace.
0100Successful Response
A single usage log entry.
Validation Error
GET /api/v1/usage HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
[
{
"api_key_id": "text",
"api_key_name": "text",
"attempt_count": 1,
"attempt_position": 1,
"billing_meters": {
"tools": {
"ANY_ADDITIONAL_PROPERTY": {
"billed": 1,
"errors": 1,
"unit_rate": 1,
"ANY_ADDITIONAL_PROPERTY": "anything"
}
},
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"bulk_editable": true,
"cache_read_tokens": 1,
"cache_write_1h_tokens": 1,
"cache_write_tokens": 1,
"completion_tokens": 1,
"cost": 1,
"counts_toward_budget": true,
"endpoint": "text",
"error_message": "text",
"id": "text",
"latency_ms": 1,
"model": "text",
"policy_name": "text",
"pricing_breakdown": [
{
"cost": 1,
"label": "text",
"meter": "text",
"unit_rate": 1,
"units": 1,
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"prompt_tokens": 1,
"provider": "text",
"provider_latency_ms": 1,
"reasoning_tokens": 1,
"request_group_id": "text",
"selection_reason": "text",
"source": "text",
"source_label": "text",
"status": "text",
"status_code": 1,
"stream_cut_by": "provider",
"tags": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"timestamp": "text",
"total_tokens": 1,
"user_alias": "text",
"user_id": "text"
}
]Delete imported usage rows by explicit ids or by filter.
Target either the current selection (ids) or everything matching a filter (by_filter: true plus optional source / model / user_id / status / date range / priced). Only imported rows (counts_toward_budget = false) are ever removed: enforced gateway rows and the spend ledger (users.spend) are untouched, so a delete can never desync a budget. Master-key only.
Enter your API key here (sent as Otari-Key header).
Selection of imported usage rows to delete.
falseSuccessful Response
How many imported rows the delete removed.
0Validation Error
DELETE /api/v1/usage HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 336
{
"api_key_id": "text",
"by_filter": false,
"end_date": "2026-01-01T00:00:00.000Z",
"endpoint": "text",
"ids": [
"text"
],
"model": "text",
"priced": true,
"provider": "text",
"source": "text",
"source_label": "text",
"start_date": "2026-01-01T00:00:00.000Z",
"status": "text",
"tool": "text",
"user_id": "text",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000"
}{
"deleted": 0
}Total number of usage logs matching the given filters.
Serves the dashboard paginator's "N of M" total without changing the bare array contract of GET /api/v1/usage. Runs only when the client asks (a separate request), so the COUNT(*) is not paid on every page load. With counts_toward_budget=false it also backs the "select all N matching this filter" affordance for bulk delete / set-price, which touch imported rows only.
That value is the one place this count is narrower than GET /api/v1/usage: it also excludes rows this deployment served itself, so the number an operator confirms is the number the mutation can reach. The list still pages the budget-exempt gateway rows it omits.
Enter your API key here (sent as Otari-Key header).
Return logs with timestamp >= start_date (ISO 8601 or Unix epoch seconds)
Return logs with timestamp < end_date (ISO 8601 or Unix epoch seconds)
Filter to one or more users; repeatable (user_id=a&user_id=b). Several values match any of them. At most 50 per call.
Filter to a single status: 'success', 'error', or 'absorbed' (an attempt a routing policy recovered from, excluded from error_count and request_count)
Filter to a single failure status code (e.g. 429 for provider rate limits, 402 for missing-pricing rejections). Only error rows carry one, so this filter also restricts to status='error' unless 'status' is given explicitly
Filter to one or more models; repeatable (model=a&model=b). Several values match any of them. At most 50 per call.
Filter to a single endpoint (e.g. '/v1/chat/completions')
Filter to a single provider (e.g. 'openai')
Filter to a single provenance source (e.g. 'gateway' or 'claude_code')
Filter to a single session (source_label): the session's trace id on a gateway request that named one, or the session/project label imported usage carried
Filter by a request tag (what a request sent in its metadata), as key:value. Repeatable: values for the same key match any of them, and different keys must all match. At most 50 per call.
Filter to one or more API key ids; repeatable (api_key_id=a&api_key_id=b). Several values match any of them. At most 50 per call.
Filter by token-pricing state: true = only rows whose model tokens were priced, false = only rows that still need pricing (no cost at all, or tokens that were never metered because the model had no rate). A row charged only for gateway-run tool calls still counts as needing pricing.
Filter to requests that ran a gateway-run tool. 'any' matches any tool; a tool name (web_search, web_fetch, code_execution) matches that tool specifically.
Filter by budget participation: true = only enforced gateway rows, false = only imported rows, narrowed past the filter of the same name on GET /api/v1/usage so the total matches what bulk delete and set-price can reach
Filter to the rows of one or more request groups; repeatable (request_group_id=a&request_group_id=b). A routed request writes one row per attempt, all sharing a request_group_id, so this returns a request's whole plan: its absorbed attempts and the attempt that served it. Ignore ordering by timestamp and read attempt_position to reconstruct the plan. At most 1000 ids per call.
Only usage recorded in this workspace.
Successful Response
Total number of usage logs matching a set of filters.
Validation Error
GET /api/v1/usage/count HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
{
"total": 1
}Ingest a batch of externally-observed usage events.
Authenticated with either an API key or the master key. Usage binds to the authenticated principal: an API key attributes to its own user (and stamps its id on the rows); the master key may name any user via user_id. Records subscription-backed usage (e.g. Claude Code) as usage-log rows tagged with their source, priced at the effective API rate for each event's timestamp. Imported usage is real cost, but never counts toward budgets or mutates users.spend (it is retrospective, so it cannot be reserved). Idempotent by (source, source_event_id). The payload is content-free; any prompt/completion/tool field is rejected (422), not stored.
Enter your API key here (sent as Otari-Key header).
A batch of imported usage events sharing a source and default user.
extra="forbid" here mirrors the per-event schema: a stray content field at
the batch level (e.g. a top-level prompt) is a 422, not silently ignored.
^[a-zA-Z0-9._:-]+$Successful Response
Per-batch outcome. Re-submitting is safe: prior events count as duplicates.
000Validation Error
POST /api/v1/usage/external-events HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 377
{
"events": [
{
"cache_read_tokens": 0,
"cache_tokens_in_prompt": false,
"cache_write_1h_tokens": 0,
"cache_write_tokens": 0,
"duration_ms": 1,
"input_tokens": 0,
"model": "text",
"output_tokens": 0,
"provider": "text",
"reasoning_tokens": 0,
"session_label": "text",
"source_event_id": "text",
"status": "success",
"timestamp": "2026-01-01T00:00:00.000Z",
"user_id": "text"
}
],
"source": "text",
"user_id": "text"
}{
"accepted": 0,
"duplicate": 0,
"errors": [
{
"detail": "text",
"index": 1,
"source_event_id": "text"
}
],
"rejected": 0
}Requests the gateway is currently serving, longest-running first.
A usage row is written when a request settles, so the log alone cannot answer "is anything happening right now": on a slow backend, a 30-second local model call is invisible until it finishes. This reports what is in progress.
Read from an in-memory registry, so it describes the process that answers this call and not the deployment: behind a load balancer, consecutive polls reach different otari processes, and there is no deployment-wide total to ask for. total is the true in-flight count for the answering process even when requests is capped.
Enter your API key here (sent as Otari-Key header).
Successful Response
The requests in flight on the answering worker.
GET /api/v1/usage/in-flight HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
Successful Response
{
"requests": [
{
"api_key_id": "text",
"elapsed_ms": 1,
"endpoint": "text",
"id": "text",
"model": "text",
"policy_name": "text",
"provider": "text",
"started_at": "2026-01-01T00:00:00.000Z",
"user_id": "text"
}
],
"total": 1
}Look up a request's settled cost by the Otari-Request-ID it was sent.
This is how a caller recovers the cost of a request whose response never carried one: a stream that failed or was disconnected mid-response, or a request that errored. An API key sees only the requests it made; the master key sees any. Returns 404 until the request has settled (its rows are written by a background writer, so a lookup made the instant a stream closes can precede them), and for an id that is unknown or belongs to another key, with no way to tell those apart. A stream that failed, including one the provider cut, always writes an error row. A stream the client abandoned before the provider reported usage, with no gateway tool work, writes a row only under the estimate policy, billed on an estimate; otherwise it writes none, so its id stays 404.
Enter your API key here (sent as Otari-Key header).
Successful Response
What one request settled at, summed over every usage row it wrote.
A routed request writes a row per attempt and a vision-normalized one a row for
the describe call, all sharing the Otari-Request-ID the caller was sent as
their request_group_id, so this is the request's whole bill rather than one
attempt's. cost_usd uses the inline usage.cost_usd format and is null
when no row was priced.
Validation Error
GET /api/v1/usage/requests/{request_id} HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
{
"completion_tokens": 1,
"cost_usd": "text",
"prompt_tokens": 1,
"request_id": "text",
"row_count": 1,
"status": "success",
"total_tokens": 1
}Time series split by one dimension, for the dashboard's stacked charts.
Same filters and window bounds as /summary (kept in lockstep: the dashboard serializes one filter object for both, and a filter this endpoint silently ignored would make the stacked chart disagree with the tiles beside it). The window's top groups by spend are returned as their own series; everything past the top eight folds into a single other series per bucket, so the stack always reconciles with the summary totals. Points are sparse (populated cells only); the bucket grid is bounded like /summary's series, so an hourly bucket over a too-wide window is rejected rather than ballooning the payload.
Enter your API key here (sent as Otari-Key header).
Dimension to split the series by
Return logs with timestamp >= start_date (ISO 8601 or Unix epoch seconds)
Return logs with timestamp < end_date (ISO 8601 or Unix epoch seconds)
Filter to one or more users; repeatable (user_id=a&user_id=b). Several values match any of them. At most 50 per call.
Filter to a single status: 'success', 'error', or 'absorbed' (an attempt a routing policy recovered from, excluded from error_count and request_count)
Filter to a single failure status code (e.g. 429 for provider rate limits, 402 for missing-pricing rejections). Only error rows carry one, so this filter also restricts to status='error' unless 'status' is given explicitly
Filter to one or more models; repeatable (model=a&model=b). Several values match any of them. At most 50 per call.
Filter to a single endpoint (e.g. '/v1/chat/completions')
Filter to a single provider (e.g. 'openai')
Filter to a single provenance source (e.g. 'gateway' or 'claude_code')
Filter to a single session (source_label): the session's trace id on a gateway request that named one, or the session/project label imported usage carried
Filter by a request tag (what a request sent in its metadata), as key:value. Repeatable: values for the same key match any of them, and different keys must all match. At most 50 per call.
Filter to one or more API key ids; repeatable (api_key_id=a&api_key_id=b). Several values match any of them. At most 50 per call.
Filter by token-pricing state: true = only rows whose model tokens were priced, false = only rows that still need pricing (no cost at all, or tokens that were never metered because the model had no rate). A row charged only for gateway-run tool calls still counts as needing pricing.
Filter to requests that ran a gateway-run tool. 'any' matches any tool; a tool name (web_search, web_fetch, code_execution) matches that tool specifically.
Filter by budget participation, which is not the same question as provenance: true = only enforced gateway rows, false = every row that never touches a budget, meaning imported usage and also gateway traffic on a budget-exempt key
Only usage recorded in this workspace.
Time-series granularity: 'hour' or 'day'
dayPossible values: Successful Response
A per-group time series for the dashboard's stacked charts.
groups ranks the window's top groups by spend (plus the reconciling
other fold), in the order a chart should stack and color them; points
is sparse (only populated cells), keyed by canonical UTC bucket_start.
Validation Error
GET /api/v1/usage/series?group_by=model HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
{
"bucket": "hour",
"end_date": "text",
"group_by": "model",
"groups": [
{
"cost": 1,
"is_other": false,
"key": "text",
"label": "text",
"requests": 1,
"tokens": 1
}
],
"points": [
{
"bucket_start": "text",
"cost": 1,
"is_other": false,
"key": "text",
"requests": 1,
"tokens": 1
}
],
"start_date": "text"
}Set the cost of imported usage rows from manual per-1M rates.
Target either the current selection (ids) or everything matching a filter (by_filter: true). Cost / billing meters / pricing breakdown are recomputed from each row's own token counts at the supplied input / output / cache_read / cache_write per-1M rates (manual rates, not a recompute from configured pricing). Only imported rows (counts_toward_budget = false) are touched, so users.spend is never affected. Master-key only.
Enter your API key here (sent as Otari-Key header).
Selection of imported usage rows plus the manual per-1M rates to price them at.
input and output are required (every row is charged for them); the cache
rates are optional and, when omitted, those tokens fold into the fresh-input charge
exactly as an unpriced cache rate does in normal metered pricing.
falseSuccessful Response
Outcome of a manual repricing pass.
matched imported rows were recomputed; updated had their stored cost
changed and unchanged already matched the recomputed value.
000Validation Error
POST /api/v1/usage/set-price HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 460
{
"api_key_id": "text",
"by_filter": false,
"cache_read_price_per_million": 1,
"cache_write_price_per_million": 1,
"end_date": "2026-01-01T00:00:00.000Z",
"endpoint": "text",
"ids": [
"text"
],
"input_price_per_million": 1,
"model": "text",
"output_price_per_million": 1,
"priced": true,
"provider": "text",
"source": "text",
"source_label": "text",
"start_date": "2026-01-01T00:00:00.000Z",
"status": "text",
"tool": "text",
"user_id": "text",
"workspace_id": "123e4567-e89b-12d3-a456-426614174000"
}{
"matched": 0,
"unchanged": 0,
"updated": 0
}Aggregate spend, tokens, and request volume for the dashboard Usage page.
Range-bounded (default last 30 days, hard-capped): unlike the raw /api/v1/usage list, every aggregate is scoped to a bounded window so it stays served by the timestamp index. Returns grand totals, breakdowns by model / user / API key / source / session (source_label) / endpoint / provider (top rows plus a reconciling other fold, billed token counts), the error taxonomy grouped by failure status code, and a UTC-bucketed time series carrying each bucket's error count and billed token composition (input incl. cache, cache read/write, output).
Each breakdown is its own GROUP BY pass, so a caller that reads only the totals or the series should narrow dimensions rather than pay for all eight (the dashboard's tiles, timeline context, and model typeahead all do). Omitting the parameter keeps the full set.
model, user_id, and api_key_id are repeatable: several values match any of them, so one chart can compare a handful of models, users, or keys.
Enter your API key here (sent as Otari-Key header).
Return logs with timestamp >= start_date (ISO 8601 or Unix epoch seconds)
Return logs with timestamp < end_date (ISO 8601 or Unix epoch seconds)
Filter to one or more users; repeatable (user_id=a&user_id=b). Several values match any of them. At most 50 per call.
Filter to a single status: 'success', 'error', or 'absorbed' (an attempt a routing policy recovered from, excluded from error_count and request_count)
Filter to a single failure status code (e.g. 429 for provider rate limits, 402 for missing-pricing rejections). Only error rows carry one, so this filter also restricts to status='error' unless 'status' is given explicitly
Filter to one or more models; repeatable (model=a&model=b). Several values match any of them. At most 50 per call.
Filter to a single endpoint (e.g. '/v1/chat/completions')
Filter to a single provider (e.g. 'openai')
Filter to a single provenance source (e.g. 'gateway' or 'claude_code')
Filter to a single session (source_label): the session's trace id on a gateway request that named one, or the session/project label imported usage carried
Filter by a request tag (what a request sent in its metadata), as key:value. Repeatable: values for the same key match any of them, and different keys must all match. At most 50 per call.
Filter to one or more API key ids; repeatable (api_key_id=a&api_key_id=b). Several values match any of them. At most 50 per call.
Filter by token-pricing state: true = only rows whose model tokens were priced, false = only rows that still need pricing (no cost at all, or tokens that were never metered because the model had no rate). A row charged only for gateway-run tool calls still counts as needing pricing.
Filter to requests that ran a gateway-run tool. 'any' matches any tool; a tool name (web_search, web_fetch, code_execution) matches that tool specifically.
Filter by budget participation, which is not the same question as provenance: true = only enforced gateway rows, false = every row that never touches a budget, meaning imported usage and also gateway traffic on a budget-exempt key
Only usage recorded in this workspace.
Time-series granularity: 'hour' or 'day'
dayPossible values: A tag key to break spend down by, returned as by_tag. Rows that do not carry the tag group under a null key.
Successful Response
Aggregate spend/volume for the Usage & analytics page.
Every breakdown field is always present. One the caller excluded through
dimensions comes back as an empty list, the same shape a window with no
matching rows produces, so narrowing the selector never changes the schema.
Validation Error
GET /api/v1/usage/summary HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
{
"bucket": "hour",
"by_api_key": [
{
"cost": 1,
"is_other": false,
"key": "text",
"label": "text",
"requests": 1,
"tokens": 1
}
],
"by_endpoint": [
{
"cost": 1,
"is_other": false,
"key": "text",
"label": "text",
"requests": 1,
"tokens": 1
}
],
"by_model": [
{
"cost": 1,
"is_other": false,
"key": "text",
"label": "text",
"requests": 1,
"tokens": 1
}
],
"by_provider": [
{
"cost": 1,
"is_other": false,
"key": "text",
"label": "text",
"requests": 1,
"tokens": 1
}
],
"by_source": [
{
"cost": 1,
"is_other": false,
"key": "text",
"label": "text",
"requests": 1,
"tokens": 1
}
],
"by_source_label": [
{
"cost": 1,
"is_other": false,
"key": "text",
"label": "text",
"requests": 1,
"tokens": 1
}
],
"by_tag": [
{
"cost": 1,
"is_other": false,
"key": "text",
"label": "text",
"requests": 1,
"tokens": 1
}
],
"by_tool": [
{
"calls": 1,
"cost": 1,
"errors": 1,
"requests": 1,
"tool": "text"
}
],
"by_user": [
{
"cost": 1,
"is_other": false,
"key": "text",
"label": "text",
"requests": 1,
"tokens": 1
}
],
"end_date": "text",
"errors_by_status_code": [
{
"error_class": "pricing",
"requests": 1,
"status_code": 1
}
],
"series": [
{
"bucket_start": "text",
"cache_read_tokens": 0,
"cache_write_tokens": 0,
"cost": 1,
"errors": 0,
"input_tokens": 0,
"output_tokens": 0,
"requests": 1,
"tokens": 1
}
],
"start_date": "text",
"totals": {
"avg_latency_ms": 1,
"billed_input_tokens": 0,
"billed_output_tokens": 0,
"cache_read_tokens": 1,
"cache_write_1h_tokens": 1,
"cache_write_tokens": 1,
"completion_tokens": 1,
"cost": 1,
"error_count": 1,
"prompt_tokens": 1,
"reasoning_tokens": 0,
"request_count": 1,
"total_tokens": 1,
"unpriced_requests": 0
}
}Last updated
Was this helpful?
