ProductDesktopUsage provider APIs

Agent usage provider APIs

Maps vetted provider quota APIs, authentication, semantics, provenance, and jackin❯ coverage gaps.

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.

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

  1. Every provider in scope has a workable availability source, and jackin❯ already calls the right endpoint for six of seven — 01. 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, 08.
    • Claude: de-facto GET api.anthropic.com/api/oauth/usage (OAuth Bearer + anthropic-beta: oauth-2025-04-20 + claude-code/<ver> 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, 09.
    • 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, 11.
    • 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.
    • 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.

  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, 07.

  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.

  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 Q1, 08 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.
    • Amp "Amp Free" plan label is hardcoded despite Megawatt/Gigawatt subscriptions; no public capture of paid-plan displayText exists — 04, 10 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.
    • 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, 01.
    • Codex account/read decoder tag mismatch: expects "apikey", upstream sends "apiKey" + "amazonBedrock"; decode error fails the whole RPC usage result — 08 Q2.
    • z.ai: observed plan field data.level not in jackin❯ alias list; auth header form (Bearer vs raw) unsettled — 06, 10 Q2.
    • MiniMax: officially documented host www.minimax.io absent from jackin❯ URL fan-out — 01.
    • Kimi: possible UA/client-whitelist gating (third-party tracker spoofs KimiCLI/1.6; jackin❯ sends jackin-capsule/usage) — 06.

  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 Q1, 03, 09.

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

  • 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.
  • 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.
  • 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.

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, 03, 05.
  • Codex per-turn x-codex-* headers / websocket events as a passive polling source (fire only on real turns) — 02.
  • account/usage/read (historical token stats) — exactly the trend payload the limits-only rule forbids — 08.
  • Anthropic Admin/Analytics APIs (org-scoped, not subscription windows) — 03.
  • 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, 11.
  • OpenUsage's spend donuts/histories as any kind of reference — forbidden surface (limits-only rule), noted in its screenshot — 10.

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.
  • 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).

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

Start with current coverage, then read the provider chapter for the account in question. Chapters 07–11 cover projection, follow-up evidence, and provenance boundaries.

03 — Daemon and integration architecture

Defines the daemon protocol, state ownership, account monitoring, GitHub integration, and native macOS boundaries for Agent Hub.

01 — jackin-usage current provider coverage

Inventories current provider probes, credential sources, normalized fields, coverage gaps, and display flow.

On this page

Research questionHeadline findingsMethod and evidenceAnalysis and candidate directionsRuled outLimitations and open questionsHow to readRelated work