# Agent usage provider APIs (https://jackin.tailrocks.com/research/product/desktop/usage-provider-apis/) **Research state:** Needs refresh Verification cutoff: 2026-07-24. Chapters 01–11 cover provider APIs, quota semantics, authentication, provenance, and implementation gaps. Informs: [jackin❯ desktop](/roadmap/native-macos-usage-menu-bar/). ## Research question [#research-question] (a) Per provider, which API exposes the availability data a limits-only menu bar shows, and which displayed elements have no direct API source; (b) semantics of the run-out projection phrases and what jackin❯ already computes; (c) what `crates/jackin-usage/` already fetches vs. gaps. ## Headline findings [#headline-findings] 1. **Every provider in scope has a workable availability source, and jackin❯ already calls the right endpoint for six of seven** — [01](/research/product/desktop/usage-provider-apis/01-current-coverage/). Per provider: * **Codex**: `GET {base}/wham/usage` (+ `/wham/rate-limit-reset-credits`, consume POST) with ChatGPT OAuth Bearer; windows carry `used_percent`, `limit_window_seconds`, `reset_after_seconds`, `reset_at`; Spark rides `additional_rate_limits[]`; credits + reset-credits are separate concepts. All first-party-sourced from openai/codex — [02](/research/product/desktop/usage-provider-apis/02-codex-api/), [08](/research/product/desktop/usage-provider-apis/08-codex-followups/). * **Claude**: de-facto `GET api.anthropic.com/api/oauth/usage` (OAuth Bearer + `anthropic-beta: oauth-2025-04-20` + `claude-code/` UA); per-window `utilization` + `resets_at` only; `limits[]` carries per-model weekly (`weekly_scoped`, display name "Fable"); no official API, endpoint 429s hard; fields multi-source corroborated — [03](/research/product/desktop/usage-provider-apis/03-claude-api/), [09](/research/product/desktop/usage-provider-apis/09-claude-followups/). * **Amp**: single RPC `POST ampcode.com/api/internal?userDisplayBalanceInfo` returning ONE server-rendered prose string (`displayText`); current Amp Free output is a daily remaining percentage plus individual/workspace balances, all client-parsed — [04](/research/product/desktop/usage-provider-apis/04-amp-api/), [11](/research/product/desktop/usage-provider-apis/11-amp-daily-followup/). * **Grok**: official CLI now open-source (xai-org/grok-build): proxy `GET cli-chat-proxy.grok.com/v1/billing?format=credits` / ACP `x.ai/billing`; consumer model = one shared weekly pool, fixed weekly reset; the billing response's `subscription_tier` is already resolved display-first by the server/official client — [05](/research/product/desktop/usage-provider-apis/05-grok-api/). * **z.ai / MiniMax / Kimi**: bearer/raw-key GETs; MiniMax is the only officially documented quota API of the three (`www.minimax.io/v1/token_plan/remains`) — [06](/research/product/desktop/usage-provider-apis/06-zai-minimax-kimi-apis/). 2. **The pace/projection phrase family is CodexBar's UI vocabulary, not API data.** "Runs out in", "Lasts until reset" confirmed verbatim on codexbar.app; "Projected empty" in CodexBar release notes; OpenUsage uses "\~N% left at reset" instead. NO provider API supplies burn rate, projection, or history for these — all client-computed — [10](/research/product/desktop/usage-provider-apis/10-provenance-and-misc/), [07](/research/product/desktop/usage-provider-apis/07-runout-projection/). 3. **Run-out projections are client-derived and outside the jackin❯ usage contract.** Provider APIs expose current limits and reset windows, not burn-rate forecasts or history. The existing pace and projection consumers are evidence of legacy surface assumptions, not a capability to complete. jackin❯ should render provider-authoritative used/remaining percentages and reset state only — [07](/research/product/desktop/usage-provider-apis/07-runout-projection/). 4. **macOS credential blocker for Claude (Desktop-critical):** default macOS Claude Code stores OAuth credentials Keychain-ONLY (service `Claude Code-credentials`) and actively unlinks `~/.claude/.credentials.json`; jackin❯ has no Keychain reader, so its Claude probe finds nothing on a default macOS host. Codex has no such hole (default store = `~/.codex/auth.json` file) — [09](/research/product/desktop/usage-provider-apis/09-claude-followups/) Q1, [08](/research/product/desktop/usage-provider-apis/08-codex-followups/) Q3. `claude setup-token` tokens are rejected by the usage endpoint (`user:inference` scope only) — only `/login` credentials work. 5. **Concrete jackin❯ gaps found** (question c): * Run-out/projection producer absent (above). * Amp parser: jackin❯ expects `$remaining/$limit + hourly replenishment` line; current Amp Free is `N% remaining today (resets daily)`. Workspace balances now have a public `amp usage` capture in the same `displayText` — [11](/research/product/desktop/usage-provider-apis/11-amp-daily-followup/). * Amp "Amp Free" plan label is hardcoded despite Megawatt/Gigawatt subscriptions; no public capture of paid-plan `displayText` exists — [04](/research/product/desktop/usage-provider-apis/04-amp-api/), [10](/research/product/desktop/usage-provider-apis/10-provenance-and-misc/) Q3. * Amp Free reports a percentage with `"resets daily"` and no exact timestamp; jackin❯ replenishment-derived reset does not represent it. Paid subscription monthly text remains unobserved — [11](/research/product/desktop/usage-provider-apis/11-amp-daily-followup/). * Grok: plan label heuristic wrong-by-design (`auth_mode=="oidc"` → "SuperGrok" also matches Free browser logins; `x.ai/billing.subscription_tier` is already resolved display-first); current `config.prepaidBalance` and positive enabled `onDemandCap`/`onDemandUsed` are not extracted; cent objects need proto-zero and signed-magnitude handling; pace passes `None` though the RPC path has period bounds — [05](/research/product/desktop/usage-provider-apis/05-grok-api/), [01](/research/product/desktop/usage-provider-apis/01-current-coverage/). * Codex `account/read` decoder tag mismatch: expects `"apikey"`, upstream sends `"apiKey"` + `"amazonBedrock"`; decode error fails the whole RPC usage result — [08](/research/product/desktop/usage-provider-apis/08-codex-followups/) Q2. * z.ai: observed plan field `data.level` not in jackin❯ alias list; auth header form (Bearer vs raw) unsettled — [06](/research/product/desktop/usage-provider-apis/06-zai-minimax-kimi-apis/), [10](/research/product/desktop/usage-provider-apis/10-provenance-and-misc/) Q2. * MiniMax: officially documented host `www.minimax.io` absent from jackin❯ URL fan-out — [01](/research/product/desktop/usage-provider-apis/01-current-coverage/). * Kimi: possible UA/client-whitelist gating (third-party tracker spoofs `KimiCLI/1.6`; jackin❯ sends `jackin-capsule/usage`) — [06](/research/product/desktop/usage-provider-apis/06-zai-minimax-kimi-apis/). 6. **Plan labels are mostly client-side.** Server-provided: Grok (`x.ai/billing.subscription_tier`, resolved display-first upstream), z.ai (`level`, single observation), Codex (`plan_type` enum — distinguishes `pro`/`prolite` but carries no "5x"/"20x" labels; first-party renders "Pro"/"Pro Lite"; jackin❯ "Pro 20x"/"Pro 5x" is a marketing-level inference). Client-inferred: Claude (stored credential metadata), Amp (nothing), Kimi (web surface only) — [08](/research/product/desktop/usage-provider-apis/08-codex-followups/) Q1, [03](/research/product/desktop/usage-provider-apis/03-claude-api/), [09](/research/product/desktop/usage-provider-apis/09-claude-followups/). ## Method and evidence [#method-and-evidence] The dossier compares provider responses, official or first-party clients, public captures, and the current jackin❯ adapters at the declared cutoff. Every volatile conclusion is bounded by the chapter that owns its source and authentication method. ## Analysis and candidate directions [#analysis-and-candidate-directions] * **Run-out producer**: Variant A (linear-from-window-start; zero new data; jumpy early-window, wrong for rolling windows — but windows verified fixed-slot) vs Variant C (sampled burn from consecutive snapshots; smoother, needs history the store doesn't retain — one in-memory delta available today) vs Variant B (nominal pace; misleading for idle accounts). Producer belongs Rust-side (Swift splitter already exists) — [07](/research/product/desktop/usage-provider-apis/07-runout-projection/). * **Claude on macOS**: add a Keychain reader (macOS consent UI; "Always Allow" makes future reads silent while "Allow" may prompt again; `security find-generic-password -s "Claude Code-credentials"` / Security.framework) vs file-only + documented limitation vs waiting on anthropics#22144 (credential-export feature request) — [09](/research/product/desktop/usage-provider-apis/09-claude-followups/). * **Grok plan/credits**: adopt the billing response's already-resolved `subscription_tier`; surface signed-normalized `prepaidBalance` and current on-demand used strictly behind a positive enabled cap as quota bounds — [05](/research/product/desktop/usage-provider-apis/05-grok-api/). ## Ruled out [#ruled-out] * Any official/public REST usage API for Claude subscription windows (closed "not planned"), Codex ChatGPT-plan windows (private backend per openai/codex#29618), or Grok consumer windows (docs.x.ai is developer-API only) — [02](/research/product/desktop/usage-provider-apis/02-codex-api/), [03](/research/product/desktop/usage-provider-apis/03-claude-api/), [05](/research/product/desktop/usage-provider-apis/05-grok-api/). * Codex per-turn `x-codex-*` headers / websocket events as a passive polling source (fire only on real turns) — [02](/research/product/desktop/usage-provider-apis/02-codex-api/). * `account/usage/read` (historical token stats) — exactly the trend payload the limits-only rule forbids — [08](/research/product/desktop/usage-provider-apis/08-codex-followups/). * Anthropic Admin/Analytics APIs (org-scoped, not subscription windows) — [03](/research/product/desktop/usage-provider-apis/03-claude-api/). * Amp structured-key fallbacks (`ampFreeRemaining` etc.) and the retired hourly-dollar compatibility reader — current CLI/API exposes only `displayText`, whose Amp Free line is daily percentage — [04](/research/product/desktop/usage-provider-apis/04-amp-api/), [11](/research/product/desktop/usage-provider-apis/11-amp-daily-followup/). * OpenUsage's spend donuts/histories as any kind of reference — forbidden surface (limits-only rule), noted in its screenshot — [10](/research/product/desktop/usage-provider-apis/10-provenance-and-misc/). ## Limitations and open questions [#limitations-and-open-questions] **Operator-gated (agreed method: operator-authenticated agent-browser sessions + live-key curls; queue for a follow-up session):** * Claude: routines window live key (`seven_day_routines` vs `seven_day_cowork`) on a routines-active account; whether `oauth/profile` returns a plan label; weekly \~72h-refresh anomaly (monperrus gist) vs documented fixed weekly reset. * Codex: live Spark `limit_name` strings; reset-credits list cap; `ChatGPT-Account-Id` header requirement; help.openai.com tier articles (Intercom SPA, browser-only). * Amp: post-subscription `displayText` under Megawatt/Gigawatt/linked-subscription accounts (no public paid-plan capture exists six days post-launch); `getUserInfo` contents. Amp Free daily format and workspace-balance line are verified by the public live capture in [11](/research/product/desktop/usage-provider-apis/11-amp-daily-followup/). * Grok: live protobuf shape of the grok.com `GetGrokCreditsConfig` web route; `/v1/settings` contract; per-tier weekly-vs-monthly assignment. * z.ai: Bearer vs raw header acceptance (two-form probe); `level` value enumeration. * MiniMax: plan-title fields presence; `api.*` vs `www.` host equivalence. * Kimi: exact `/coding/v1/usages` schema, plan field, UA gating; OAuth-token acceptance on the API-key surface. **Scoped out:** OpenCode probe surface (exists in jackin❯, outside the seven providers of this topic — [01](/research/product/desktop/usage-provider-apis/01-current-coverage/)). **Assumptions safe to plan on:** fixed-slot windows anchored on `resets_at`; one-parser-covers-both for Claude Keychain/file credential JSON; Swift stays display-only with Rust producing any new label strings. ## How to read [#how-to-read] Start with [current coverage](/research/product/desktop/usage-provider-apis/01-current-coverage/), then read the provider chapter for the account in question. Chapters 07–11 cover projection, follow-up evidence, and provenance boundaries. ## Related work [#related-work] * [Account-limit telemetry](/research/agents/telemetry/token-cost-telemetry/) * [jackin❯ desktop Agent Hub](/research/product/desktop/agent-hub/) * [Usage visual references](/research/product/desktop/usage-visual-references/)