---
title: "Usage summary"
method: GET
path: "/client/usage"
tags: ["Usage"]
---

# Usage summary

`GET /client/usage`

## Request

- Base URL: `https://api.roar-ai.com`
- URL: `https://api.roar-ai.com/client/usage`
- Auth: HTTP bearer

Token counts, request volume, latency, and cost — headline totals, a per-model breakdown, and the recent requests themselves. Model calls only: tool gateway calls are reported by `GET /client/usage/tools`. Requires `usage:read`.

## Query parameters

- `from` string, date
- `to` string, date
- `limit` integer
- `keyId` string, uuid

## Response `200`

Usage report

- UsageReport
  - `summary` UsageSummary, required
    - `requests` integer, required
    - `inputTokens` integer, required
    - `outputTokens` integer, required
    - `costUsd` string, required: Decimal USD as a string
    - `cacheSavingsUsd` string, required: What the provider's prompt cache saved over the base input rate. A different mechanism from `cacheHits`, over a disjoint set of requests.
    - `promptCacheRequests` integer, required: Requests that contributed to `cacheSavingsUsd`
    - `avgLatencyMs` integer, required
    - `p95LatencyMs` integer, required
    - `avgTtftMs` integer, required: Average time to first token, streaming requests only
    - `cacheHits` integer, required: Requests answered from the response cache — no upstream call, billed $0
    - `failovers` integer, required: Requests that needed more than one attempt
    - `errors` integer, required: Requests that failed. Excludes cancellations — see `clientAborted`.
    - `clientAborted` integer, required: Requests the caller hung up on before they finished
    - `builtinToolUsd` string, required: The part of `costUsd` charged for built-in tools such as web search — included in `costUsd`, not added to it
    - `builtinToolCalls` object, required: How many of each priced built-in tool ran, e.g. `{ "web_search": 12 }`
  - `byModel` ModelUsage[], required
    - `model` string, nullable, required: The model the caller asked for. NULL when `internalFeature` is set: that row is one of our own features calling a model on your behalf, and which model it chose is ours rather than yours.
    - `internalFeature` string, nullable, required: Set when this row is a platform feature — the automatic deploy fix, or setup advice — rather than a request you made. Billed to you like any other usage; grouped here by the feature so the spend is accountable without naming a model you never chose.
    - `requests` integer, required
    - `costUsd` string, required: Decimal USD as a string
    - `inputTokens` integer, required
    - `outputTokens` integer, required
    - `avgLatencyMs` integer, required
    - `errors` integer, required
  - `data` UsageRecord[], required: Recent requests, newest first (`limit`, default 100)
    - `id` integer, required
    - `apiKeyId` string, uuid, nullable, required
    - `requestedModel` string, nullable, required: The model you asked for. Null when Roar made the call for you — see internalFeature
    - `internalFeature` string, nullable, required: Set when Roar made this call on your behalf: `insight` (app setup advice), `autofix` (automatic deploy fix), `explain` (deploy failure explainer). Null for your own requests
    - `endpoint` string, required
    - `status` integer, required: HTTP status we answered with
    - `inputTokens` integer, nullable, required
    - `outputTokens` integer, nullable, required
    - `costUsd` string, required: Decimal USD as a string
    - `builtinToolCalls` object, nullable, required: Built-in tools that ran on this call, e.g. `{ "web_search": 2 }`; null when none did
    - `builtinToolUsd` string, required: The part of `costUsd` charged for those tools — included in it, not added
    - `latencyMs` integer, nullable, required
    - `cached` boolean, required
    - `requestId` string, nullable, required
    - `errorCode` string, nullable, required
    - `ttftMs` integer, nullable, required: Time to the first token, for a streamed call: when the first text, reasoning or tool call arrived. Null when not streamed, or when no output arrived
    - `toolsAuto` boolean, required: Roar added your company's tools to this request itself — the app's “Let this app's AI use its tools” switch
    - `documentPages` integer, nullable, required: PDF pages we read for this request so the model could take them. Null when no document was converted
    - `documentScannedPages` integer, nullable, required: Of those pages, how many were scans sent to the model as page images. Null when no document was converted
    - `ignoredParams` string[], nullable: Sampling settings this request was served without, because the model runs at a fixed configuration (temperature, top_p). Also sent as the x-roar-ignored-params response header. Null when none were
    - `via` 'mcp' | 'null', nullable, required: mcp when an assistant connected over MCP made this call with the send_message or generate_image tool; null for every other call
    - `createdAt` string, date-time, required

## Other responses

- `403`: Key lacks usage:read

---

[API](https://skmtc.dev/roar-ai/apis/roar-ai-api.md) · [All operations](https://skmtc.dev/roar-ai/apis/roar-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/roar-ai/apis/roar-ai-api/revisions/37e4d0d5a7fe?raw)