Overview
GET /v1/usage returns the caller’s own consumption and limits — no admin
access needed. It answers three questions in one call:
- How much have I used (requests, tokens, estimated cost)?
- How much budget do I have left, and when does it reset?
- Which rate limits apply to me, and how much headroom remains?
Quick example
Whose usage you see
- Managed API key — the key’s bound
user_pathis used. No parameters needed, and the key holder cannot read outside their own subtree. - Master key (or unsafe mode) — pass
X-GoModel-User-Pathto pick a path, or omit it to see/(everything):
Response fields
usage
Aggregated from tracked requests over the date window, with the same token and
estimated-cost semantics as the dashboard. Cost
fields are null when no matched request has pricing. The whole block is
null when no storage backend records usage (USAGE_ENABLED=false or no
database).
budgets
One entry per budget covering the path — including
budgets inherited from ancestor paths such as /. remaining can go
negative and usage_ratio above 1 — both mean the budget is blown through;
exceeded mirrors enforcement, so when it is true requests are rejected
until period_end (period_seconds of 2592000 is the calendar-month
sentinel, not a literal 30 days). resets_in_seconds counts down to
period_end relative to server_time, so it is safe to render without
worrying about client clock skew.
rate_limits
Live counters for every user-path rate limit rule
covering the path. max_tokens/tokens_remaining/tokens_usage_ratio
appear only on rules with token limits; a period_label of concurrent
marks an in-flight cap, where in_flight is the current count (and feeds
requests_usage_ratio). The *_usage_ratio fields are used/limit per
dimension, unclamped — token windows can overshoot past 1. exhausted is
true when any dimension is fully used, and resets_in_seconds counts down
to window_end relative to server_time (omitted for concurrent rules,
which have no window). Provider- and model-scoped rules are not listed: they
describe shared infrastructure capacity, not the caller.
Rate limit counters live in memory and are saved to the database about once
a second at the default
RATE_LIMITS_FLUSH_INTERVAL=1. A restart restores
the last saved counts once; a crash can lose the counts since the last
flush. Replicas sharing a database report the cluster-wide count, which can
trail the other replicas’ latest traffic by about two seconds (with 0,
replicas stop seeing each other’s new counts after startup); see
several replicas share one limit.
Budgets are the durable numbers, computed from stored usage records.Date window
Theusage block defaults to the last 30 days (UTC day boundaries). Narrow it
with query parameters — days, or explicit start_date/end_date
(YYYY-MM-DD, 365-day maximum):
usage.
Cache mode
Theusage block counts provider-bound requests only, so it lines up with
budgets and cost. Response-cache hits are recorded too, and
cache_mode brings them into view:
cached with the default is the quickest read on how much of your
traffic the cache is absorbing. Unrecognized values fall back to uncached.
cache_mode affects only usage: budgets and rate limits never count cache
hits, because a hit spends nothing and consumes no quota.