Expose quota usage and billing-period timing in the status line payload #5029

Feature request: expose quota usage and billing-period timing in the status line payload

Context

The configurable status line (statusLine.command) receives a JSON payload on stdin. Today the account-level usage information in it is limited to cost.total_premium_requests, which is a per-session count:

cost: {
  total_api_duration_ms,
  total_lines_added,
  total_lines_removed,
  total_duration_ms,
  total_premium_requests   // this session only
}

The payload does not say how much of the user's quota or allowance has been consumed, what the allowance is, or when the current period starts and ends. The CLI itself knows this: the built-in usage display shows quota/monthly figures, and account.getQuota exists (see #4504).

Problem

A status line script cannot show whether the user is on pace to exhaust their allowance before it resets. I tried to build a "pace" indicator: percent of quota used compared to percent of the billing period elapsed, so you can tell at a glance whether you are burning quota too fast. It can't be done from the payload, because the script has neither the quota usage nor the period boundaries.

The workarounds are poor:

• Summing total_premium_requests only covers the current session, not the account's usage for the period.
• Reading ~/.copilot/session-state/<id>/events.jsonl (the alternative rejected in Expose total_files_modified in the status line payload #3404) is fragile and still doesn't give the allowance or reset date.
• Calling GitHub's billing/usage APIs from the script on every refresh needs separate auth, is rate-limited, and is slow against the status line's refresh budget. The CLI already holds this data.

Proposal

Add a quota object to the status line payload, populated from data the CLI already fetches. For example:

quota: {
  used: 142,                              // units consumed this period (premium requests or AI credits)
  limit: 300,                             // allowance for the period; null if unlimited
  used_percentage: 47.3,                  // null if unlimited
  period_start: "2026-09-01T00:00:00Z",   // ISO 8601
  period_end:   "2026-10-01T00:00:00Z",   // reset time
  unit: "premium_requests"
}

Minimum useful set: used, limit (or null for unlimited), and period_end (reset time). period_start is helpful but can be derived from the period length.

Notes:

• For unlimited plans, still send used and period_* so scripts can show spend. This overlaps with Show monthly usage when AI credits are unlimited #3649.
• If quota data is unavailable (BYOK, offline, fetch failed), omit the field or send null so scripts can degrade gracefully.
• A pace indicator could then be computed in a few lines of script:
  pace = (used / limit) - (now - period_start) / (period_end - period_start)

Use case

Status line showing quota pace, e.g. Quota 47% · period 33% · +14% ahead of pace · resets in 20d.

Prior art

Claude Code's status line input includes rate-limit usage percentages and reset timestamps, which makes pace-style indicators possible there.

Related

• Expose total_files_modified in the status line payload #3404, Expose per-model token usage (model_usage array) in the status line payload #3405: other payload additions that expose existing runtime state
• Show monthly usage when AI credits are unlimited #3649: monthly usage display when credits are unlimited
• Monthly Usage Tracking #1880: monthly usage tracking
• account.getQuota returns the request timestamp as resetDate instead of the quota reset date #4504: account.getQuota reset date