ProductDesktopUsage provider APIs

05 — Grok usage API

Documents Grok billing windows, plan labels, authentication, wire-field uncertainty, and presentation semantics.

Summary

Grok exposes a weekly subscription limit and reset bounds, but plan labeling and parts of the wire contract remain uncertain.

Question and scope

(1) Which endpoint(s) expose subscription usage/limits for SuperGrok-style plans — billing-cycle/weekly window, percent left, reset time? (2) Is the plan label ("SuperGrok") an API field or client-side inference? (3) What auth is used and where is it stored on disk (location/type only)? Does the primary evidence confirm jackin❯ "billing cycle only, no session window" note (grok.rs:198)? (4) Which display elements (deficit %, "Runs out in" projection) have no direct API source and need client-side computation?

This chapter informs jackin-desktop.

Method

Method: web + codebase cross-reference; current official billing source rechecked after plan cold review at xai-org/grok-build main Verification cutoff: 2026-07-24

Primary-source situation changed in July 2026: xAI open-sourced the official grok CLI/agent runtime as xai-org/grok-build ("synced periodically from the SpaceXAI monorepo" — the repo's own branding; xAI org on GitHub). Its billing extension, auth model, and user guide are now first-party evidence for everything below. Clean-room constraint respected: no CodexBar or OpenUsage source was read; one non-banned third-party client (Raycast agent-usage extension) is cited as corroboration only. No embedded instructions were found in any fetched content.

Findings

Q1 — Endpoints exposing SuperGrok subscription usage/limits

Q2 — Plan label ("SuperGrok"): API field or client-side inference?

Q3 — Auth: type, on-disk location; "billing cycle only, no session window"

  • Credential store: ~/.grok/auth.json (owner-only 0600; MCP OAuth tokens separately in ~/.grok/mcp_credentials.json). Default flow is browser OAuth at auth.x.ai; device-code and external-provider flows write the same file; hot-reloaded on change. — https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-pager/docs/user-guide/02-authentication.md (confidence: HIGH)
  • File format: JSON map scope-string → credential object (AuthStore = BTreeMap<String, GrokAuth>), entries carrying key (Bearer JWT), refresh_token, expires_at, auth_mode (web_login/oidc/external/api_key), user_id, email, team/org fields. Scope keys: OIDC issuer-derived (auth.x.ai), legacy "https://accounts.x.ai/sign-in", API-key "xai::api_key". — https://github.com/xai-org/grok-build/blob/main/crates/codegen/xai-grok-shell/src/auth/model.rs#L11-L14, #L47-L95, #L259. jackin❯ parser matches this: scans https://auth.x.ai::-prefixed and legacy /sign-in scopes for key + expires_at — grok.rs:508-531. Types/locations only; no values reproduced. (confidence: HIGH)
  • Precedence: per-model key > session token from auth.json > XAI_API_KEY env fallback. — 02-authentication.md ("Auth Precedence"). jackin❯ additionally probes XAI_API_KEY/GROK_DEPLOYMENT_KEY env presence (grok.rs:29-30) and a container handoff copy of auth.json (GROK_HANDOFF_AUTH_PATH, usage.rs:186). (confidence: HIGH)
  • Bearer JWT suffices for billing — no session cookie required. Official CLI sends Authorization: Bearer (+ X-XAI-Token-Auth, x-userid) to the proxy billing endpoint — billing.rs#L213-L226; jackin❯ (grok.rs:465-477) and Raycast (fetcher.ts#L91-L97) both hit the grok.com gRPC-web route with Bearer only. (confidence: HIGH for proxy; MED for the grok.com web route, unofficial)
  • grok.rs:198 claim — confirmed for "no session window", refined for "billing cycle": no session-scoped (rolling hours) quota window exists anywhere in the official billing surface; the quota window is the usage period — now typically weekly (USAGE_PERIOD_TYPE_WEEKLY, unified consumer pool) with a monthly variant, plus the deprecated monthly billing cycle. Official label choice is driven by the period-type enum ("Weekly limit"/"Monthly limit", fallback "Usage") — credit_bar.rs#L38-L47 — whereas jackin❯ infers Weekly/Monthly from window duration or reset distance because the scraped web protobuf lacks the enum (grok.rs:314-334). jackin❯ own comments already treat the cycle as the Weekly-slot filler (grok.rs:198-199, :242). (confidence: HIGH)

Q4 — Display elements with NO direct API source (client-side computation)

  • Deficit/reserve pace ("N% in deficit" / "N% in reserve" / "On pace"): no Grok API field. jackin❯ computes it by comparing remaining-percent against the fraction of the window still left — crates/jackin-usage/src/usage/format.rs (lines 164–191). The official CLI ships no pace concept at all (credit bar shows usage %, next reset, credits, PAYG only — credit_bar.rs#L106-L152). Grok buckets in jackin❯ currently pass no pace label (None at grok.rs:215 web branch, :259 RPC branch). (confidence: HIGH)
  • "Runs out in" projection: no Grok API field supplies burn rate, projected depletion time, or equivalent; GetGrokCreditsConfig carries only point-in-time used-percent + period bounds (+ per-period history). Any runout estimate must be extrapolated client-side. Desktop renders it only if the Rust side ever emits it in pace_label — native/Sources/JackinDesktop/UsageWindow/ProviderCardView.swift:209-229. (confidence: HIGH)
  • Percent left: derived (100 − used); official CLI computes the complement of floored usage (credit_bar.rs#L208-L214), jackin❯ does 100 - used.round() (grok.rs:210, :254). (confidence: HIGH)
  • Window length for pace math on the web-scrape path: jackin❯ protobuf scrape recovers only used_percent + reset_at_epoch (grok.rs:553-600), so window duration (needed for any pace/deficit computation) is unavailable there; the proxy/ACP path does provide currentPeriod.start+end, from which the window is derivable. (confidence: HIGH)
  • Available in API but unused for display: per-period history and per-product productUsage exist in the credits config (billing.rs#L107-L108, #L567-L569 — "productUsage is still unused by the CLI billing surface"); jackin❯ limits-only product rule excludes historical trend surfaces regardless (crates/jackin-usage/CLAUDE.md hard rule). (confidence: HIGH)

Dead ends and contradictions

  • docs.x.ai has no consumer-subscription usage API. Rate-limits and consumption pages are developer-API-tier only; Management API (management-api.x.ai) is team API billing. Checked and ruled out as a SuperGrok usage source. — https://docs.x.ai/developers/rate-limits, https://docs.x.ai/developers/rest-api-reference/management/billing
  • Third-party blog limit tables (jingrey.com etc.) claiming fixed daily message counts (e.g. "300–500 texts/24h") are stale/unsourced — they describe the pre-2026 per-product daily-limit era; the official FAQ now documents the unified weekly pool. Dropped as evidence.
  • auth_mode as plan signal contradicted: official auth model marks it token-provenance-only ("no code branches on this"), so jackin❯ oidc → SuperGrok mapping (grok.rs:793-802) can mislabel Free/X-Premium browser logins. Recorded under Q2; no recommendation made per scope.
  • Branding drift, not a contradiction: the repo prose says "SpaceXAI" while org/domain remain xai-org / x.ai / grok.com; quoted verbatim where relevant.
  • GitHub-wide search for GrokBuildBilling (excluding the clean-room-banned repos) shows ~147 third-party hits using the same grok.com gRPC-web route — corroborates it is the de-facto web endpoint, but none are primary sources; not cited as evidence beyond the one Raycast corroboration.

Implications for jackin❯

Treat Grok’s ACP billing surface as primary and the browser endpoint as fallback, while keeping consumer-plan labels and unified weekly-pool semantics evidence-qualified.

Limitations and unknowns

  • Live response shape of grok.com/grok_api_v2.GrokBuildBilling/GetGrokCreditsConfig (protobuf field numbers). jackin❯ scraper keys on heuristics (fixed32 percent at a path ending in field 1; varint epoch, preferred path [1,5,1] — grok.rs:564-595). Whether these match the current proto and whether the response now carries the USAGE_PERIOD_TYPE_* enum and productUsage per-product split needs an operator-authenticated browser session inspecting network traffic on grok.com Settings → Usage (/?_s=usage).
  • Full server contract of GET https://cli-chat-proxy.grok.com/v1/settings — only the client-side RemoteSettings struct is public (config-types lib.rs); undocumented fields and stability guarantees unknown. Same for /v1/billing?format=credits availability to non-official clients (no published API contract; header set includes X-XAI-Token-Auth and x-grok-client-version, gating behavior unverified).
  • Whether consumer chat surfaces retain any separately queryable per-product/per-model rate-limit endpoint post-unification (for non-Build products like Imagine/Voice), or whether everything folds into the credits config percent + productUsage. No primary source found; needs authenticated grok.com network inspection.
  • Weekly vs monthly period assignment per plan (which tiers get USAGE_PERIOD_TYPE_WEEKLY vs …MONTHLY, and whether is_unified_billing_user=false legacy monthly+on-demand accounts still exist in the wild) — the FAQ describes the weekly pool generally; per-tier mapping unverified.
  • JWT tier claim contract (claim name tier, numeric values 0–6) is evidenced only by the client decoder (mvp_agent/mod.rs#L117-L141); no token-format spec published. Values could change server-side without notice.

Sources

04 — Amp usage API

Documents Amp quota endpoints, credit balances, authentication paths, plan labels, and reset semantics.

06 — z.ai, MiniMax, and Kimi usage APIs

Compares subscription-quota sources, credential paths, and limit semantics for z.ai, MiniMax, and Kimi.

On this page

SummaryQuestion and scopeMethodFindingsQ1 — Endpoints exposing SuperGrok subscription usage/limitsQ2 — Plan label ("SuperGrok"): API field or client-side inference?Q3 — Auth: type, on-disk location; "billing cycle only, no session window"Q4 — Display elements with NO direct API source (client-side computation)Dead ends and contradictionsImplications for jackin❯Limitations and unknownsSourcesRelated work