[FEATURE]: Add Go plan usage/balance API endpoint (rolling/weekly/monthly windows)

[StephanMeijer]

Feature hasn't been suggested before.

• I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

Summary

Expose the Go plan subscription usage data via a public API endpoint. The dashboard already shows this information — rolling, weekly, and monthly usage percentages with reset timers — but there is no way to query it programmatically.

Use Case

• Status bar widgets (waybar, polybar, macOS menu bar) showing current usage
• Alerts when approaching plan limits before getting throttled
• Monitoring dashboards aggregating usage across providers and plans
• CI/CD pipelines checking remaining quota before kicking off expensive runs

Current Behavior

The only way to see Go plan usage is the web dashboard, which displays:

• Rolling usage: x% (resets in N minutes)
• Weekly usage: y% (resets in N minutes)
• Monthly usage: z% (resets in N minutes)

No API endpoint exists to retrieve this data.

Proposed API

GET /api/v1/usage/plan
Authorization: Bearer <api-key>

Response:
{
  "plan": "go",
  "windows": {
    "rolling": {
      "usage_percent": 65,
      "resets_in_seconds": 2520
    },
    "weekly": {
      "usage_percent": 30,
      "resets_in_seconds": 259200
    },
    "monthly": {
      "usage_percent": 12,
      "resets_in_seconds": 1728000
    }
  }
}

Related Issues

• Feature Request: Add Zen balance API endpoint #10448 — Zen balance API endpoint (pay-as-you-go USD balance; different data model)
• [FEATURE] Add unified usage tracking via /usage (#9545) #9281 — Unified /usage tracking in TUI (provider-level: Codex/Copilot/Claude)
• Github Copilot: Tracking Premium Requests #768 — Copilot premium request tracking
• Request: View token and zen usage with command #3119 — Early request for token/zen usage via command

Additional Context

The Go plan's rolling/weekly/monthly usage windows are a distinct data model from the Zen credit balance (#10448) and provider-level quotas (#9281). The server already computes this data for the dashboard, so exposing it via API should be a relatively small addition.

[github-actions]

This issue doesn't fully meet our contributing guidelines.

What needs to be fixed:

• Feature request titles must start with [FEATURE]: (current title: "Feature Request: Add Go plan usage/balance API endpoint...")
• The feature request template includes a verification checkbox confirming you've searched for existing issues — please ensure this is included

Please edit this issue to address the above within 2 hours, or it will be automatically closed.

---

This issue might be a duplicate of existing issues. Please check:

• Feature Request: Add Zen balance API endpoint #10448: Also requests a programmatic API endpoint for account balance/usage data (Zen balance endpoint — different data model but closely related functionality)

If you believe this was flagged incorrectly, please let a maintainer know.

[github-actions]

Thanks for updating the issue! It now meets our contributing guidelines — the title has been corrected to start with [FEATURE]: and the verification checkbox is checked. We appreciate you taking the time to fix it.

[github-actions]

Thanks for updating the issue! It now meets our contributing guidelines — the title has been corrected, the verification checkbox is checked, and the description clearly explains the use case and need. Much appreciated!

[peculiarnewbie]

submitted a pr #16513. but i don't think can test this locally, so it's not meeting compliance @thdxr

[StephanMeijer]

Thanks!

[alansong63]

+1. Would love to see this implemented. My use case: integrating Go plan usage tracking into an AI agent CLI as a quick command. Having rolling/weekly/monthly usage data accessible via API (e.g. GET /zen/go/v1/usage) would enable real-time monitoring without the web dashboard.

[LuisHerreraG]

+1, I would like it too to programmatically check it in a helper script or even inside of OpenCode itself!

[slkiser]

If you need a workaround is possible with OpenCode Quota: for OpenCode Go you just have to provide a workspace ID and auth cookie.