[Feature]: estimate effective Codex quota capacity from observed usage and quota history #2344

Area

Dashboard

What are you trying to accomplish?

I want OpenCodex to estimate how much effective Codex capacity a quota window represents by correlating two signals it already observes:

1. local timestamped Codex usage, including model and token-type attribution;
2. upstream Codex quota utilization (used_percent) and reset/window metadata.

The main use case is detecting whether the amount of observed workload represented by one percentage point of Codex quota changes materially over time.

For example, if OpenCodex observes:

weekly quota: 42% -> 47%
observed usage during the same interval: 620 Codex-equivalent credits
it could estimate:
observed quota efficiency: 124 credits / percentage point
implied full-window capacity: ~12,400 credits
This should be presented as an observed estimate, not as OpenAI's official or contractual quota.
A derived API-equivalent value could also make the result easier to interpret:
estimated effective capacity
Codex-equivalent credits: ~12,400
API-equivalent value: ~$X
Optionally, the same capacity could be expressed as model-equivalent workload under a documented token mix, for example Sol-, Terra-, or Luna-equivalent usage.
The most useful output would be the trend rather than one isolated number:
window / observation estimated effective capacity

Aug 10 18.3k credits
Aug 11 18.0k credits
Aug 12 18.5k credits
Aug 13 17.9k credits
Aug 14 11.2k credits
This would let users distinguish ordinary subjective variation from a measurable change in observed quota efficiency.

What prevents this today?

OpenCodex already appears to have most of the required primitives, but they are not currently joined into one historical measurement.
On the usage side, OpenCodex already records timestamped request usage and model/token attribution, and the Usage work in #1058 and #1820 is extending calendar-day, model-level, cache, and estimated-cost accounting.
On the quota side, the Codex quota path already parses and stores values such as:

• weekly/monthly/short-window used_percent;
• reset_at;
• window duration;
• update time.

These values are already used for account-pool and quota-aware behavior.
The missing primitive appears to be bounded historical quota observations. The current quota cache is primarily a latest-state snapshot, so OpenCodex cannot reliably reconstruct:
quota at t0
quota at t1
usage observed between t0 and t1
after the fact.
As a result, users who want to investigate changes in Codex quota consumption currently have to manually combine local token logs with quota-percentage screenshots or external observations.
This type of manual analysis has recently been used in upstream Codex quota investigations (for example openai/codex#38728), which suggests that making the measurement reproducible locally would be useful.

What should OpenCodex do?

Add a bounded, privacy-safe quota-observation history and correlate it with authoritative local usage over matching intervals.
Conceptually:
quota observation A
timestamp = t0
weekly_used_percent = q0
reset_at = r

quota observation B
timestamp = t1
weekly_used_percent = q1
reset_at = r

local usage between t0 and t1
-> normalize by model/token type
-> derive observed workload C
Then calculate, where the observations are comparable:
delta quota = q1 - q0

observed quota efficiency
= C / delta_quota

implied full-window effective capacity
= C / (delta_quota / 100)
I would suggest using Codex-equivalent credits, or another stable normalized workload unit, as the canonical internal measure rather than raw tokens.
Raw tokens alone are misleading because input, cached input, output, and different Codex models can consume quota at very different rates.
If reliable pricing metadata is available, the UI may additionally derive:

• API-equivalent USD;
• Sol-equivalent workload;
• Terra-equivalent workload;
• Luna-equivalent workload.
  Those should remain derived presentation values rather than the authoritative stored metric.
  The implementation should also fail conservatively around discontinuities.
  For example:
• never calculate across different reset_at / quota generations;
• ignore or mark observations where quota unexpectedly decreases;
• avoid producing a confident estimate from a 0–1 percentage-point change;
• preserve unknown data as unknown;
• distinguish weekly, monthly, and short/burst windows;
• do not infer unobserved external usage.
  A small confidence/coverage indicator could make this explicit:
  Estimated effective weekly capacity
  12.4k credits

Observed quota delta: 8 pp
Observed interval: 19h
Coverage: OpenCodex traffic only
Confidence: medium

Example usage or interface

One possible Usage / Codex quota panel:
Codex effective capacity

Weekly window
────────────────────────────────────
Observed quota change 34% -> 41%
Observed workload 910 credits
Quota efficiency 130 credits / pp

Estimated full capacity ~13,000 credits
API-equivalent ~$X

vs previous estimate -28%
Confidence Medium

Based on traffic observed by OpenCodex.
Usage from other clients or shared agentic surfaces may reduce the estimate.
A historical view could show:
Date Credits / pp Implied capacity
Aug 17 181 18.1k
Aug 18 176 17.6k
Aug 19 184 18.4k
Aug 20 179 17.9k
Aug 21 116 11.6k
The first implementation does not need a complex chart. A compact table or trend indicator would already make the data useful.

Alternatives or workarounds

Today this can be approximated manually by:

1. recording Codex quota percentage at two times;
2. extracting local usage for the same interval;
3. normalizing the usage by model/token type;
4. dividing observed workload by the quota-percentage change.
   This is cumbersome, difficult to reproduce, and loses historical quota observations unless the user records them separately.
   Using raw token totals alone is also not sufficient because different models and token classes have different quota/credit weights.

Additional context

This appears complementary rather than duplicative with existing Usage work:

• [Feature]: add single-day/custom date filtering and daily model metrics to Usage #1058 tracks calendar-day/custom-range filtering and daily model metrics.
• [Feature]: add provider/model estimated cost and cache metrics to Usage #1820 tracks provider/model token, cache, and estimated-cost accounting.
• Existing Codex quota infrastructure already provides current quota percentages and reset/window metadata.
  A possible composition would be:
  [Feature]: add single-day/custom date filtering and daily model metrics to Usage #1058
  -> reliable time-range selection

#1820
-> normalized model/token usage accounting

Codex quota observations
-> bounded quota history

this proposal
-> correlate both sides
-> estimate effective quota efficiency/capacity
The feature should explicitly avoid claiming to reveal OpenAI's internal quota formula or official subscription allowance.
There are several reasons the estimate can differ from the actual upstream allowance:

• OpenCodex may not observe all usage associated with the same account;
• other supported agentic surfaces may share an allowance;
• quota percentages may be rounded;
• upstream weighting or policy may change;
• short-window and long-window limits are separate.
  For that reason, names such as:
• Observed quota efficiency
• Estimated effective capacity
• API-equivalent capacity
  would be preferable to Actual quota.
  The main value is detecting relative changes under a consistent measurement method, not asserting an undocumented absolute limit.

Checks

• I searched existing issues and documentation.
• This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
• I removed secrets and personal data.