For the complete documentation index, see llms.txt. This page is also available as Markdown.

Usage

List Usage

get

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).

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Query parameters
start_datestring · date-time · nullableOptional

Return logs with timestamp >= start_date (ISO 8601 or Unix epoch seconds)

end_datestring · date-time · nullableOptional

Return logs with timestamp < end_date (ISO 8601 or Unix epoch seconds)

user_idstring[] · max: 50 · nullableOptional

Filter to one or more users; repeatable (user_id=a&user_id=b). Several values match any of them. At most 50 per call.

statusstring · nullableOptional

Filter to a single status: 'success', 'error', or 'absorbed' (an attempt a routing policy recovered from, excluded from error_count and request_count)

status_codeinteger · nullableOptional

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

modelstring[] · max: 50 · nullableOptional

Filter to one or more models; repeatable (model=a&model=b). Several values match any of them. At most 50 per call.

endpointstring · nullableOptional

Filter to a single endpoint (e.g. '/v1/chat/completions')

providerstring · nullableOptional

Filter to a single provider (e.g. 'openai')

sourcestring · nullableOptional

Filter to a single provenance source (e.g. 'gateway' or 'claude_code')

source_labelstring · nullableOptional

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

tagstring[] · max: 50 · nullableOptional

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.

api_key_idstring[] · max: 50 · nullableOptional

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.

pricedboolean · nullableOptional

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.

toolstring · enum · nullableOptional

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.

Possible values:
counts_toward_budgetboolean · nullableOptional

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

request_group_idstring[] · max: 1000 · nullableOptional

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.

workspace_idstring · uuid · nullableOptional

Only usage recorded in this workspace.

skipintegerOptionalDefault: 0
limitinteger · min: 1 · max: 1000OptionalDefault: 100
Responses
200

Successful Response

application/json

A single usage log entry.

api_key_idstring · nullableRequired
api_key_namestring · nullableOptional
attempt_countinteger · nullableOptional
attempt_positioninteger · nullableOptional
billing_metersany of · nullableRequired
or
bulk_editablebooleanRequired
cache_read_tokensinteger · nullableRequired
cache_write_1h_tokensinteger · nullableRequired
cache_write_tokensinteger · nullableRequired
completion_tokensinteger · nullableRequired
costnumber · nullableRequired
counts_toward_budgetbooleanRequired
endpointstringRequired
error_messagestring · nullableRequired
idstringRequired
latency_msinteger · nullableRequired
modelstringRequired
policy_namestring · nullableOptional
prompt_tokensinteger · nullableRequired
providerstring · nullableRequired
provider_latency_msinteger · nullableRequired
reasoning_tokensinteger · nullableOptional
request_group_idstring · nullableOptional
selection_reasonstring · nullableOptional
sourcestringRequired
source_labelstring · nullableRequired
statusstringRequired
status_codeinteger · nullableRequired
stream_cut_bystring · enum · nullableOptionalPossible values:
timestampstringRequired
total_tokensinteger · nullableRequired
user_aliasstring · nullableOptional
user_idstring · nullableRequired
get/api/v1/usage
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 Usage Rows

delete

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.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Body

Selection of imported usage rows to delete.

api_key_idany of · nullableOptional
stringOptional
or
string[] · max: 50Optional
by_filterbooleanOptionalDefault: false
end_datestring · date-time · nullableOptional
endpointstring · nullableOptional
idsstring[] · max: 1000 · nullableOptional
modelany of · nullableOptional
stringOptional
or
string[] · max: 50Optional
pricedboolean · nullableOptional
providerstring · nullableOptional
sourcestring · nullableOptional
source_labelstring · nullableOptional
start_datestring · date-time · nullableOptional
statusstring · nullableOptional
toolstring · nullableOptional
user_idany of · nullableOptional
stringOptional
or
string[] · max: 50Optional
workspace_idstring · uuid · nullableOptional
Responses
200

Successful Response

application/json

How many imported rows the delete removed.

deletedintegerOptionalDefault: 0
delete/api/v1/usage
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
}

Count Usage

get

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.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Query parameters
start_datestring · date-time · nullableOptional

Return logs with timestamp >= start_date (ISO 8601 or Unix epoch seconds)

end_datestring · date-time · nullableOptional

Return logs with timestamp < end_date (ISO 8601 or Unix epoch seconds)

user_idstring[] · max: 50 · nullableOptional

Filter to one or more users; repeatable (user_id=a&user_id=b). Several values match any of them. At most 50 per call.

statusstring · nullableOptional

Filter to a single status: 'success', 'error', or 'absorbed' (an attempt a routing policy recovered from, excluded from error_count and request_count)

status_codeinteger · nullableOptional

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

modelstring[] · max: 50 · nullableOptional

Filter to one or more models; repeatable (model=a&model=b). Several values match any of them. At most 50 per call.

endpointstring · nullableOptional

Filter to a single endpoint (e.g. '/v1/chat/completions')

providerstring · nullableOptional

Filter to a single provider (e.g. 'openai')

sourcestring · nullableOptional

Filter to a single provenance source (e.g. 'gateway' or 'claude_code')

source_labelstring · nullableOptional

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

tagstring[] · max: 50 · nullableOptional

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.

api_key_idstring[] · max: 50 · nullableOptional

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.

pricedboolean · nullableOptional

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.

toolstring · enum · nullableOptional

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.

Possible values:
counts_toward_budgetboolean · nullableOptional

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

request_group_idstring[] · max: 1000 · nullableOptional

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.

workspace_idstring · uuid · nullableOptional

Only usage recorded in this workspace.

Responses
200

Successful Response

application/json

Total number of usage logs matching a set of filters.

totalintegerRequired
get/api/v1/usage/count
GET /api/v1/usage/count HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
{
  "total": 1
}

Ingest External Usage

post

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.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Body

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.

sourcestring · max: 64RequiredPattern: ^[a-zA-Z0-9._:-]+$
user_idstring · min: 1 · max: 256 · nullableOptional
Responses
200

Successful Response

application/json

Per-batch outcome. Re-submitting is safe: prior events count as duplicates.

acceptedintegerOptionalDefault: 0
duplicateintegerOptionalDefault: 0
rejectedintegerOptionalDefault: 0
post/api/v1/usage/external-events
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
}

List In Flight

get

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.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Responses
200

Successful Response

application/json

The requests in flight on the answering worker.

totalintegerRequired
get/api/v1/usage/in-flight
GET /api/v1/usage/in-flight HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
200

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
}

Get Request Settlement

get

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.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
request_idstring · max: 255Required
Responses
200

Successful Response

application/json

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.

completion_tokensintegerRequired
cost_usdstring · nullableRequired
prompt_tokensintegerRequired
request_idstringRequired
row_countintegerRequired
statusstring · enumRequiredPossible values:
total_tokensintegerRequired
get/api/v1/usage/requests/{request_id}
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
}

Usage Series

get

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.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Query parameters
group_bystring · enumRequired

Dimension to split the series by

Possible values:
start_datestring · date-time · nullableOptional

Return logs with timestamp >= start_date (ISO 8601 or Unix epoch seconds)

end_datestring · date-time · nullableOptional

Return logs with timestamp < end_date (ISO 8601 or Unix epoch seconds)

user_idstring[] · max: 50 · nullableOptional

Filter to one or more users; repeatable (user_id=a&user_id=b). Several values match any of them. At most 50 per call.

statusstring · nullableOptional

Filter to a single status: 'success', 'error', or 'absorbed' (an attempt a routing policy recovered from, excluded from error_count and request_count)

status_codeinteger · nullableOptional

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

modelstring[] · max: 50 · nullableOptional

Filter to one or more models; repeatable (model=a&model=b). Several values match any of them. At most 50 per call.

endpointstring · nullableOptional

Filter to a single endpoint (e.g. '/v1/chat/completions')

providerstring · nullableOptional

Filter to a single provider (e.g. 'openai')

sourcestring · nullableOptional

Filter to a single provenance source (e.g. 'gateway' or 'claude_code')

source_labelstring · nullableOptional

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

tagstring[] · max: 50 · nullableOptional

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.

api_key_idstring[] · max: 50 · nullableOptional

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.

pricedboolean · nullableOptional

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.

toolstring · enum · nullableOptional

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.

Possible values:
counts_toward_budgetboolean · nullableOptional

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

workspace_idstring · uuid · nullableOptional

Only usage recorded in this workspace.

bucketstring · enumOptional

Time-series granularity: 'hour' or 'day'

Default: dayPossible values:
Responses
200

Successful Response

application/json

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.

bucketstring · enumRequiredPossible values:
end_datestringRequired
group_bystring · enumRequiredPossible values:
start_datestringRequired
get/api/v1/usage/series
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 Usage Price Rows

post

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.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Body

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.

api_key_idany of · nullableOptional
stringOptional
or
string[] · max: 50Optional
by_filterbooleanOptionalDefault: false
cache_read_price_per_millionnumber · nullableOptional
cache_write_price_per_millionnumber · nullableOptional
end_datestring · date-time · nullableOptional
endpointstring · nullableOptional
idsstring[] · max: 1000 · nullableOptional
input_price_per_millionnumberRequired
modelany of · nullableOptional
stringOptional
or
string[] · max: 50Optional
output_price_per_millionnumberRequired
pricedboolean · nullableOptional
providerstring · nullableOptional
sourcestring · nullableOptional
source_labelstring · nullableOptional
start_datestring · date-time · nullableOptional
statusstring · nullableOptional
toolstring · nullableOptional
user_idany of · nullableOptional
stringOptional
or
string[] · max: 50Optional
workspace_idstring · uuid · nullableOptional
Responses
200

Successful Response

application/json

Outcome of a manual repricing pass.

matched imported rows were recomputed; updated had their stored cost changed and unchanged already matched the recomputed value.

matchedintegerOptionalDefault: 0
unchangedintegerOptionalDefault: 0
updatedintegerOptionalDefault: 0
post/api/v1/usage/set-price
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
}

Usage Summary

get

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.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Query parameters
start_datestring · date-time · nullableOptional

Return logs with timestamp >= start_date (ISO 8601 or Unix epoch seconds)

end_datestring · date-time · nullableOptional

Return logs with timestamp < end_date (ISO 8601 or Unix epoch seconds)

user_idstring[] · max: 50 · nullableOptional

Filter to one or more users; repeatable (user_id=a&user_id=b). Several values match any of them. At most 50 per call.

statusstring · nullableOptional

Filter to a single status: 'success', 'error', or 'absorbed' (an attempt a routing policy recovered from, excluded from error_count and request_count)

status_codeinteger · nullableOptional

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

modelstring[] · max: 50 · nullableOptional

Filter to one or more models; repeatable (model=a&model=b). Several values match any of them. At most 50 per call.

endpointstring · nullableOptional

Filter to a single endpoint (e.g. '/v1/chat/completions')

providerstring · nullableOptional

Filter to a single provider (e.g. 'openai')

sourcestring · nullableOptional

Filter to a single provenance source (e.g. 'gateway' or 'claude_code')

source_labelstring · nullableOptional

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

tagstring[] · max: 50 · nullableOptional

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.

api_key_idstring[] · max: 50 · nullableOptional

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.

pricedboolean · nullableOptional

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.

toolstring · enum · nullableOptional

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.

Possible values:
counts_toward_budgetboolean · nullableOptional

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

workspace_idstring · uuid · nullableOptional

Only usage recorded in this workspace.

bucketstring · enumOptional

Time-series granularity: 'hour' or 'day'

Default: dayPossible values:
group_by_tagstring · min: 1 · max: 64 · nullableOptional

A tag key to break spend down by, returned as by_tag. Rows that do not carry the tag group under a null key.

Responses
200

Successful Response

application/json

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.

bucketstring · enumRequiredPossible values:
end_datestringRequired
start_datestringRequired
get/api/v1/usage/summary
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?