ChatGPT Codex quota research

Question

Is there a reliable first-party API, local account state, or documented observable signal that can report remaining weekly ChatGPT Codex quota for the current account, and what authentication or privacy constraints would a Pi status integration need to respect?

Findings

Pi supports ChatGPT Plus or Pro subscription authentication for OpenAI Codex through /login. The providers docs list “ChatGPT Plus/Pro (Codex)” under subscription providers and state that OpenAI Codex requires a ChatGPT Plus or Pro subscription. The OpenAI Codex provider implementation uses https://chatgpt.com/backend-api as its base URL and OAuth through auth.openai.com. Sources: docs/providers.md; node_modules/@earendil-works/pi-ai/dist/providers/openai-codex.js; node_modules/@earendil-works/pi-ai/dist/auth/oauth/openai-codex.js.

Pi stores OAuth credentials in ~/.pi/agent/auth.json and refreshes expired tokens automatically. The providers docs describe auth storage for subscription providers, and the OpenAI Codex OAuth implementation returns an access token, refresh token, expiration time, and ChatGPT account id extracted from the access-token JWT. Requests include Authorization: Bearer <token> and chatgpt-account-id headers. Sources: docs/providers.md; node_modules/@earendil-works/pi-ai/dist/auth/oauth/openai-codex.js; node_modules/@earendil-works/pi-ai/dist/api/openai-codex-responses.js.

The installed Pi/OpenAI Codex integration does not expose a proactive “remaining weekly quota” API. Searching the installed Pi and @earendil-works/pi-ai code found no quota, balance, or remaining-usage endpoint for OpenAI Codex. The OpenAI Codex provider code has streaming request handling and OAuth, but no first-party quota read operation. Sources: node_modules/@earendil-works/pi-ai/dist/providers/openai-codex.js; node_modules/@earendil-works/pi-ai/dist/auth/oauth/openai-codex.js; node_modules/@earendil-works/pi-ai/dist/api/openai-codex-responses.js.

Pi can detect some limit information only when the provider returns an error. The OpenAI Codex response code treats error codes such as usage_limit_reached, usage_not_included, and rate_limit_exceeded, or HTTP 429, as usage-limit conditions. If the error body includes plan_type, it includes that in a friendly message. If the error body includes resets_at, it computes an approximate minutes-until-reset message. This is useful for displaying “you are out” and reset time after a failing request, but it is not a reliable way to display remaining quota before the limit is hit. Sources: node_modules/@earendil-works/pi-ai/dist/api/openai-codex-responses.js error handling.

Pi extensions can observe provider response status and normalized headers through after_provider_response, but header availability depends on provider and transport. The docs show using this hook to inspect HTTP 429 and retry-after. The OpenAI Codex transport uses both SSE and WebSocket paths, so relying on response headers for a stable weekly quota display would need live verification and may not work for all Codex requests. Sources: docs/extensions.md section after_provider_response; node_modules/@earendil-works/pi-ai/dist/api/openai-codex-responses.js.

Authentication and privacy constraints are significant. A quota integration that calls ChatGPT backend APIs directly would need access to the user's OAuth access token and ChatGPT account id. Those are credentials and account identifiers. Any status integration must avoid logging them, avoid exposing them through status rows or transcript entries, and should only call endpoints that are documented or already used by Pi's provider stack. Sources: docs/providers.md auth storage description; node_modules/@earendil-works/pi-ai/dist/auth/oauth/openai-codex.js; node_modules/@earendil-works/pi-ai/dist/api/openai-codex-responses.js request headers.

Answer

This research established only a narrower fact: Pi's installed OpenAI Codex provider and Pi's docs do not expose a documented proactive quota API. That is not enough to conclude that no reliable quota source exists. The user reported third-party applications that show this information, possibly including baby-menu, so the broader question remains open and is tracked in 064-pi-ui-third-party-codex-quota-research.

The reactive signal remains useful: a provider error can report that a usage limit was hit, and may include plan type and reset time. A safe fallback can show:

last known Codex limit error, if one occurs
reset estimate from resets_at, when present
retry-after from response headers, when present
“quota unknown” otherwise

Do not rule out a proactive quota display until the third-party mechanism has been researched.

Limitations

This research did not call ChatGPT backend APIs with the user's credentials. That was intentional because probing undocumented authenticated endpoints has privacy and stability risks.

OpenAI may expose quota information in web UI internals or undocumented backend endpoints, but no first-party documented source was established here. Treat that as an evidence gap rather than an implementation basis.

Citations

/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/providers.md, “Subscriptions” and “OpenAI Codex”.
/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/docs/extensions.md, section after_provider_response.
/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/node_modules/@earendil-works/pi-ai/dist/providers/openai-codex.js.
/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/node_modules/@earendil-works/pi-ai/dist/auth/oauth/openai-codex.js.
/nix/store/rg248h9sz8dylm8p6a9w9fj4zrv4sgm5-pi-coding-agent-0.82.1/lib/node_modules/pi-monorepo/node_modules/@earendil-works/pi-ai/dist/api/openai-codex-responses.js.

6.1 KiB Raw Blame History