Skip to content
Documentation
Dashboard
API referenceUsage API

Usage API

Spend, tokens and safe request history for every family on your key.

Model protocol

Programmatic access to usage

Usage API is a Guard extension for monitoring your own key. It shows balance, aggregates and request history for Claude, Kimi, Composer and Grok, including free token counting where supported. It is not the Anthropic organization Admin API and does not grant access to other keys.

GET /v1/usage — aggregates

ParameterRule
starting_atRFC 3339 window start; defaults to 30 days before ending_at
ending_atExclusive RFC 3339 upper bound; defaults to the start of tomorrow UTC
bucket_widthOnly 1d
bash
curl -G https://api.guardrelay.ai/v1/usage \
  -H "x-api-key: $GUARD_API_KEY" \
  --data-urlencode "starting_at=2026-07-01T00:00:00Z" \
  --data-urlencode "ending_at=2026-07-08T00:00:00Z" \
  --data-urlencode "bucket_width=1d"
json
{
  "object": "usage_report",
  "starting_at": "2026-07-01T00:00:00.000Z",
  "ending_at": "2026-07-08T00:00:00.000Z",
  "bucket_width": "1d",
  "current_balance": {
    "scope": "key_including_inflight_reservations",
    "credit_usd": "100.00000000",
    "used_usd": "3.42000000",
    "remaining_usd": "96.58000000"
  },
  "retention": {
    "detailed_days": 90,
    "detailed_starting_at": "2026-04-09T12:00:00.000Z",
    "daily_aggregates": "lifetime"
  },
  "tracking_started_at": "2026-07-01T08:30:00.000Z",
  "data": [],

The example is abridged: data and by_model are intentionally empty. data, totals, tracked_totals, and by_model contain selected inference requests across all families, including zero-cost outcomes; free count_tokens calls are separated and not added to their token or cost totals. token_counting covers count calls in the selected window, while tracked_token_counting covers them since tracking_started_at; both operations remain visible individually in /v1/usage/requests. tracking_started_at is a lower coverage bound and can be null until the first event is recorded; after the earliest detail is compacted, it is rounded down to the UTC start of the first aggregate day. daily_aggregates: "lifetime" means compacted tracked daily buckets are retained without expiry; it does not recreate history from before tracking began. Every *_usd field is a string with 8 decimal places; timestamps are RFC 3339 UTC (Z). starting_at and ending_at must be UTC day boundaries; the maximum window is 366 days.

GET /v1/usage/requests — individual calls

ParameterRule
starting_at / ending_atRFC 3339 with a timezone; defaults to the last 90 days
limit1–100; default 50
cursorThe signed opaque token from next_cursor; pass it unchanged. It freezes the original page's window and filters
statusAn exact status from the list below
outcomeA coarse group: success, failed, cancelled, or interrupted; combines with status using AND
operationmessages or count_tokens
bash
curl -G https://api.guardrelay.ai/v1/usage/requests \
  -H "x-api-key: $GUARD_API_KEY" \
  --data-urlencode "status=server_tool_error" \
  --data-urlencode "operation=messages" \
  --data-urlencode "limit=50"
json
{
  "object": "list",
  "data": [
    {
      "request_id": "req_0123456789abcdef0123456789abcdef",
      "created_at": "2026-09-09T11:20:31.120Z",
      "completed_at": "2026-09-09T11:20:32.960Z",
      "operation": "messages",
      "status": "server_tool_error",
      "retryable": false,
      "http_status": 200,
      "latency_ms": 1840,
      "model": "claude-opus-5",
      "stream": false,
      "usage": {
        "input_tokens": 840,
        "output_tokens": 90,
        "cached_input_tokens": 0,

Statuses

  • pending, success, client_error, rate_limited, policy_refusal.
  • upstream_error, stream_error, server_tool_error, internal_error.
  • cancelled means the client cancelled the request; interrupted means a service restart interrupted it.
  • retryable tells an automated client whether retrying the call is sensible.
  • Free count_tokens calls also appear in the ledger, with zero cost.

Retention and privacy

  • Detailed logical events are retained for 90 days; the current lower detail boundary is returned as retention.detailed_starting_at.
  • Older tracked events are compacted into daily aggregates that are retained without expiry. Requests before tracking_started_at are not backfilled.
  • These endpoints do not return prompts, responses, URLs/search queries, document content, tool arguments, IPs, User-Agent, or raw errors.
  • Internal request-processing, account, and network details are not exposed. Errors are normalized to safe code + message pairs.
  • Pagination runs newest to oldest: when has_more=true, pass next_cursor unchanged as the next cursor. You may omit the window and filters because the cursor restores them; if repeated, they must match exactly. A modified, foreign, or malformed cursor receives the same 400 Invalid cursor response.

Kimi, Composer and Grok

The family filter accepts all, claude, kimi, composer and grok. Omitting it selects every family.

Kimi spend, its own rates and the reserve formula are covered on Kimi · Pricing, reserve and usage.

How to select the Kimi rows

Kimi spend sits in the same report as everything else: the key and the balance are shared. Two active filters select it, family and endpoint; they combine as AND.

FilterWhat it takes
familyall, claude, kimi, composer, grok; default all
modeRemoved: any value returns 410 product_modes_removed; omit this parameter
endpointchat_completions, messages, responses, search, fetch, token_estimate or all
bash
curl -G https://api.guardrelay.ai/v1/usage \
  -H "Authorization: Bearer $GUARD_API_KEY" \
  --data-urlencode "family=kimi" \
  --data-urlencode "bucket_width=1d"
bash
curl -G https://api.guardrelay.ai/v1/usage/requests \
  -H "Authorization: Bearer $GUARD_API_KEY" \
  --data-urlencode "family=kimi" \
  --data-urlencode "endpoint=chat_completions" \
  --data-urlencode "limit=50"

Documentation sections

On this page