Feature: Add Grok Build usage quota endpoint support

[NYTEMODEONLY]

Problem

Grok Build (the coding agent on xAI's platform) shows usage quotas in the console dashboard (weekly usage %, voice usage %, reset available), but there is no public API endpoint for these metrics that third-party tools like CodexBar can query.

Current State

CodexBar's xAI plugin tracks:

• Prepaid balance via management-api.x.ai/v1/billing/teams/{team}/prepaid/balance
• 30-day spend history via the Management API's /usage endpoint

What's missing:

• Grok Build weekly usage quota (% used)
• Voice usage (% used)
• Reset-available date/time info
• Free-tier vs. paid-tier breakdown
• Any subscription-based quota data

Request

Can xAI expose dedicated usage/quota endpoints for:

1. Grok Build — weekly token/agent usage against plan limits
2. Grok Voice — voice minutes/usage against plan limits
3. Account-level quota summary — similar to how the console dashboard works

These would complement the existing Management API (which is built for team pay-as-you-go billing) and cover the subscription/plan-based usage tracking that Grok Build uses.

Why This Matters

Tools like CodexBar aggregate usage across providers in one place. Without Grok Build endpoints, users have to check console.x.ai manually for their plan limits, breaking the unified dashboard experience that works for OpenAI, DeepSeek, etc.

References

• CodexBar xAI plugin: Sources/CodexBarCore/Resources/Plugins/xai.js
• xAI Management API docs: https://console.x.ai
• Current Management API base: management-api.x.ai

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed September 5, 2026, 6:00 AM ET / 10:00 UTC.

Summary
Keep open as an owner-backed enhancement for the remaining quota coverage. Shared Grok credits, reset timestamps, and plan labeling are already released; the recent RPC sample adds useful evidence for product-specific expansion. Repository policy also prohibits automatic closure.

Reproducibility: not applicable. this requests additional quota coverage, rather than reporting a reproducible failure of the existing shared-credit display.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.

Maintainer decision needed

Question	Recommendation
Does the new GetGrokCreditsConfig sample justify supporting per-product usage now, or should that expansion remain upstream-blocked pending a stable field contract?	Retain a narrowed upstream tracker: Track only the missing product, Voice, and tier details while awaiting verified semantics for those fields.

Why: The owner already approved tracking the request, but the new evidence does not settle product identities, quota denominators, or Voice support; accepting that contract needs explicit sign-off.

Next step
Review the new RPC field contract and narrow the remaining scope before commissioning implementation; this is not a bounded existing-behavior repair.

Review details

Best possible solution:

Extend the existing Grok provider only with verified product-quota semantics, preserving its shared credit window and the separate xAI billing boundary.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this requests additional quota coverage, rather than reporting a reproducible failure of the existing shared-credit display.

Is this the best way to solve the issue?

Partly: the existing Grok integration already covers endpoint access and aggregate credits; extending its parser and shared presentation is preferable to adding a parallel xAI quota path once the remaining field semantics are verified.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The supplied sample does not establish stable product identifiers, percentage denominators, Voice coverage, or a free-versus-paid breakdown; product shares must not be assumed to represent independent quota limits.

Codex review notes: model internal, reasoning high; reviewed against 4d27bb113e5e.

Label changes

Label justifications:

• P3: This adds optional provider detail beyond the released shared-credit display and reports no broken existing workflow.

Evidence reviewed

What I checked:

• Repository identity and review revision: The origin remote identifies steipete/codexbar, and the checked-out HEAD matches the supplied current-main revision. The working tree was clean before and after inspection. (4d27bb113e5e)
• Explicit owner direction: The owner explicitly requested keeping this enhancement open pending a supported or sufficiently stable upstream contract: Feature: Add Grok Build usage quota endpoint support #2989 (comment). The supplied repository profile independently disallows automatic closure.
• Recent discussion supplies a concrete API lead: The September 4 comment supplies decoded GetGrokCreditsConfig output with aggregate usage, productUsage entries, and a current period, while acknowledging unpublished enum details: Feature: Add Grok Build usage quota endpoint support #2989 (comment). The reporter also linked the external request at Feature request: Expose Grok Build usage quota and voice usage endpoints xai-org/xai-sdk-python#196. The supplied text was inspected; embedded commands were not executed.
• The suggested RPC is already integrated: The existing web billing fetcher calls GetGrokCreditsConfig and parses an aggregate percentage and reset timestamp. Endpoint access itself is therefore already implemented. (Sources/CodexBarCore/Providers/Grok/GrokWebBillingFetcher.swift:122, 4d27bb113e5e)
• Existing proxy quota contract: The CLI proxy parser reads creditUsagePercent, currentPeriod.end, and subscription tier; focused tests cover weekly percentage/reset parsing and preserve unknown usage when the percentage is absent. These tests were read, not run. (Sources/CodexBarCore/Providers/Grok/GrokCreditsProxyFetcher.swift:59, 4d27bb113e5e)
• Remaining product breakdown is absent: The Grok snapshot projects one primary credit window, with secondary and tertiary windows absent; local session totals feed token history separately. Searches of Swift and Markdown sources found no productUsage, Grok Voice, or remaining-reset integration. (Sources/CodexBarCore/Providers/Grok/GrokStatusProbe.swift:65, 4d27bb113e5e)

Likely related people:

• steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• olddonkey: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[steipete]

Thanks for the detailed writeup. To set expectations: the core ask here — Grok Build weekly quota, voice usage, reset dates, tier breakdown — is blocked on xAI, not on CodexBar. Those numbers exist only in the console dashboard today; the Management API exposes prepaid balance and spend history (which CodexBar already reads) but no quota endpoints. Until xAI ships a public endpoint (or the console API becomes stable/documented enough to rely on), there is nothing safe for us to poll. Scraping the console session is fragile and against our approach for authenticated dashboards.

What CodexBar can do today, and does since 0.51.0: prepaid balance, 30-day spend, weekly credit windows via the CLI-proxy credits path, and correct subscription tier labeling (SuperGrok Heavy just landed via #2991).

If you have contacts at xAI, the most useful ask is a GET /v1/usage/quotas style endpoint on the Management API returning window percentages + reset timestamps per product (Build, Voice). The moment something like that exists, wiring it into the existing Grok provider is straightforward — please ping this issue if you see it appear in their docs. Keeping this open as an upstream-blocked enhancement.

[NYTEMODEONLY]

Appreciate the clear picture, Peter.

To confirm the plan:

• We've opened a parallel request directly to xAI via xai-org/xai-sdk-python#196 asking for the endpoint you described (window % + reset timestamps per product: Build, Voice).
• If/when that ships, we'll ping this issue to get it wired into the Grok provider.
• Meanwhile, thanks for CodexBar already covering prepaid balance, 30-day spend, weekly credit windows, and tier labeling in 0.51.0.

Will follow up here if we see it in their docs.

[gianpaj]

BTW, this PR seems to be doing this by parsing the local Grok CLI session and log files: #3236

But similar to how we're getting the number of reset coupons (PR #3188 ), we could use the https://grok.com/grok_api_v2.GrokBuildBilling/GetGrokCreditsConfig API used by both Grok CLI and grok.com

---

On macOS, to decode the protobuf payload:

printf '%s'
'PROTOBUF_PAYLOAD' \
  | base64 -D \
  | dd bs=1 skip=5 count=109 2>/dev/null \
  | protoc --decode_raw

The useful interpretation is:

{
  "config": {
    "creditUsagePercent": 100,
    "productUsage": [
      { "product": 2, "usagePercent": 46 }, // Grok Build
      { "product": 7, "usagePercent": 45 }, // App Builder
      { "product": 4, "usagePercent": 7 },  // Chat
      { "product": 8, "usagePercent": 2 }   // Automations
    ],
    "currentPeriod": {
      "type": 2,
      "start": "2026-08-28T13:21:21.177227Z",
      "end": "2026-09-04T13:21:21.177227Z"
    }
  },
  "grpcStatus": 0
}

So this account had used 100% of its weekly pool. The four product categories add up to 100%.

The official xAI Grok Build source identifies the main properties as creditUsagePercent,
productUsage, and currentPeriod. Exact enum names for product IDs 7 and 8, plus boolean fields 11
and 13, require xAI's unpublished protobuf schema.

Also, protoc --decode_raw shows values such as 0x42c80000 because it cannot distinguish a float
from a generic fixed32 without the schema:

0x42c80000 = 100
0x42380000 = 46 // grok build
0x42340000 = 45
0x40e00000 = 7
0x40000000 = 2

Curl command:

grok_bearer=$(
  jq -er \
    '[.[] | .key? | select(type == "string" and length > 0)][0]' \
    "$HOME/.grok/auth.json"
)

grok_response=$(mktemp -t grok-credits)
trap 'unset grok_bearer; trash "$grok_response"' EXIT

printf '\0\0\0\0\0' |
  curl --silent --show-error --fail-with-body \
    --config <(
      printf 'header = "Authorization: Bearer %s"\n' "$grok_bearer"
    ) \
    --header 'Origin: https://grok.com' \
    --header 'Referer: https://grok.com/?_s=usage' \
    --header 'Accept: */*' \
    --header 'Content-Type: application/grpc-web+proto' \
    --header 'Connect-Protocol-Version: 1' \
    --header 'x-grpc-web: 1' \
    --header 'x-user-agent: connect-es/2.1.1' \
    --data-binary @- \
    --output "$grok_response" \
    'https://grok.com/grok_api_v2.GrokBuildBilling/GetGrokCreditsConfig'

frame_type=$(xxd -p -l 1 "$grok_response")
[[ "$frame_type" == "00" ]] || {
  printf 'Expected a gRPC-Web data frame, got 0x%s\n' "$frame_type" >&2
  exit 1
}

frame_hex=$(xxd -p -l 4 -s 1 "$grok_response")
payload_bytes=$((16#$frame_hex))

dd if="$grok_response" bs=1 skip=5 count="$payload_bytes" 2>/dev/null |
  protoc --decode_raw

The important part is extracting the first frame's declared length and passing only those payload bytes to protoc. The remaining bytes contain the grpc-status trailer.

[steipete]

The existing Grok provider already reads aggregate weekly credits through the CLI proxy and GetGrokCreditsConfig, and now supports reset coupons via #3188. Thanks @gianpaj for the decoded productUsage sample. It establishes a useful response shape, but not independent Build/Voice quota limits: at 100% aggregate usage, the product percentages do not establish their denominator. Keeping this open for verified per-product/tier semantics; no speculative endpoint or quota calculation was added.

[steipete]

Reviewed #3900’s newer proxy fixture alongside the earlier RPC sample. They add useful product-usage evidence, but neither establishes Voice coverage or verified per-product denominators. Keeping this tracker open; aggregate credits, reset windows, and existing plan behavior remain unchanged.

[olddonkey]

Follow-up on the productUsage denominator question: I have samples below 100% with two products. They're from the same account on 2026-09-25, and the CLI proxy ?format=credits and grok.com GetGrokCreditsConfig returned identical values:

UTC	creditUsagePercent	GrokBuild (id 2)	GrokChat (id 4)
before	1	1	—
00:46	2	1	1
00:50	3	1	2
00:53	4	1	3
00:58	6	2	4

Between samples the only change was grok.com chat usage, and GrokChat appeared as a second entry. At every point the product percentages add up to the aggregate, including the unequal splits (3 = 2+1, 4 = 3+1, 6 = 4+2). A "share of usage" reading would make them sum to 100 regardless of the aggregate, so each product is a percentage of the same weekly pool. Values are whole percents on both surfaces.

Voice: grok CLI 1.0.41's voice mode is dictation over wss://api.x.ai/v1/stt. About 3 hours of transcribed audio produced no billing change and no product entry, so I still have no Voice fixture.

#3975 supersedes #3900. It checks these four live payloads in as verbatim test fixtures and shows the shares only as text rows under the single weekly bar. Rows appear only when they add up to creditUsagePercent within 1 pp; otherwise the card falls back to today's single bar.