Skip to main content

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?
Everything is scoped to the caller’s effective user path, so a tool holding a managed API key — an OpenCode plugin, a CLI, a status widget — can poll it with the key it already uses for inference. Polling does not consume rate limit quota.

Quick example

Whose usage you see

  • Managed API key — the key’s bound user_path is used. No parameters needed, and the key holder cannot read outside their own subtree.
  • Master key (or unsafe mode) — pass X-GoModel-User-Path to 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

The usage 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):
Budgets and rate limits always report their own live periods; the window only affects usage.

Cache mode

The usage 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:
Comparing 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.

Errors

Last modified on November 5, 2026