DocsAPIUsage

Usage.

Aggregated analytics for your account. Total calls, tokens, latency, daily breakdown, recent runs — everything the dashboard renders is also available here.

§ 01Endpoint

GET/api/usage

Authenticates with the essarion_session cookie. Like the key endpoints, this is the management plane — it powers the dashboard's analytics view, and it's available to your own admin tooling.

NoteUsage figures are eventually consistent. Calls land in the analytics roll-up within roughly 60 seconds of completion. For real-time accounting, read usage from each query response directly.

§ 02Response shape

Three top-level objects. summary is the headline numbers. daily is the call-count time series. recent is the audit feed of recent runs.

summary

Field	Type	Description
total_calls	number	Lifetime call count across all keys on the account.
ok_calls	number	Calls that returned `status: "ok"`.
error_calls	number	Calls that returned `status: "error"` or non-2xx HTTP.
tokens_in	number	Total input tokens consumed.
tokens_out	number	Total output tokens generated.
avg_latency_ms	number	Mean wall-clock latency across all calls.
last_24h	number	Calls in the trailing 24 hours.
last_7d	number	Calls in the trailing seven days.

daily

An array of { day, calls } entries, one per day, ordered ascending by date. The window covers the last 30 days. Days with zero traffic still appear, with calls: 0 — handy for plotting.

recent

The 50 most recent calls, ordered descending by created_at. Each entry's request_id deep-links to the run timeline.

Field	Type	Description
id	string	Internal id for the call record (distinct from `request_id`).
query	string	The original question, truncated to 200 characters.
status	string	`ok` or `error`.
latency_ms	number	Wall-clock latency for this call.
tokens_in	number	Input tokens consumed.
tokens_out	number	Output tokens generated.
created_at	string	ISO-8601 timestamp.
request_id	string	Run id. Fetch the timeline at `/api/v1/runs/{request_id}`.
key_name	string	Name of the API key that made this call (or `"session"` for browser-originated runs).

§ 03Examples

curl

curl https://api.essarion.com/api/usage \
  -H "Cookie: essarion_session=$ESSARION_SESSION"

§ 04Example response

Truncated for clarity — daily would normally have 30 entries and recent up to 50.

json

{
  "summary": {
    "total_calls": 14823,
    "ok_calls": 14710,
    "error_calls": 113,
    "tokens_in": 8214002,
    "tokens_out": 28941280,
    "avg_latency_ms": 16240,
    "last_24h": 412,
    "last_7d": 2890
  },
  "daily": [
    { "day": "2026-04-02", "calls": 88 },
    { "day": "2026-04-03", "calls": 102 },
    { "day": "2026-04-04", "calls": 0 },
    { "day": "2026-05-01", "calls": 412 }
  ],
  "recent": [
    {
      "id": "call_98421",
      "query": "Compare GDPR and CCPA on data subject deletion rights.",
      "status": "ok",
      "latency_ms": 18420,
      "tokens_in": 612,
      "tokens_out": 2240,
      "created_at": "2026-05-01T14:22:36Z",
      "request_id": "req_01HXYZABC123",
      "key_name": "prod-backend"
    },
    {
      "id": "call_98420",
      "query": "Summarize this morning's FOMC release...",
      "status": "ok",
      "latency_ms": 12810,
      "tokens_in": 420,
      "tokens_out": 1810,
      "created_at": "2026-05-01T14:18:11Z",
      "request_id": "req_01HXYZABC120",
      "key_name": "prod-backend"
    }
  ]
}

TipFor your own dashboards, the most useful field is recent[].request_id — it lets you pivot from any aggregate back into the full reasoning trail of any individual run. Build a deep link from each row to your own UI's run viewer.