[FEATURE]: Expose balance and monetary usage data via the official usage API

[donrami]

[FEATURE]: Expose balance and monetary usage data via the official API

Target: github.com/anomalyco/opencode (new issue)
Drafted: 2026-08-12
Drafted by: pi-go-bars maintainer (this draft is a deliverable of specs/002-official-usage-api)

---

Summary

The usage API shipped in #16513 (closing #16017) returns rolling, weekly, and
monthly plan-window usage as server-computed percentages and reset timestamps,
plus a balance-billing flag. It does not expose balance amounts or monetary
usage for accounts on balance billing (pay-as-you-go).

Use case

Headless clients — TUI extensions, dashboards, gateway operators — need balance
visibility without scraping HTML or holding session cookies. Before the API
existed, projects like pi-go-bars scraped the workspace /billing page for
balance (USD), monthly usage (USD), and monthly limit (USD). The new API made
the plan-window view official. The monetary view is still missing, which keeps
the scraping pattern alive for balance-billing accounts.

Request

Extend the official API — either add fields to GET /zen/go/v1/usage or add a
sibling endpoint (for example /zen/v1/billing) — authenticated with the same
Bearer API key, returning server-computed values:

• current balance (USD)
• monthly usage (USD)
• monthly limit (USD)
• reset timestamps

Why

• Closes the last remaining dashboard-scraping use case.
• Consistent with the existing design: server-computed values, API-key auth,
  no session cookies.
• Lets extension authors drop their cookie-based code paths entirely.

References

• [FEATURE]: Add Go plan usage/balance API endpoint (rolling/weekly/monthly windows) #16017 — original request for a usage/balance API
• feat(console): add go usage endpoint #16513 — merged usage endpoint (plan-window percentages only)

[donrami]

Closed as duplicate of #10448

[github-actions]

Thanks for updating the title! There is still one item to address before this issue is fully compliant:

• Missing verification checkbox: Feature requests require a checkbox confirming the feature hasn't already been requested. Please add something like:

  - [ ] I have searched existing issues and this has not been requested before

Please edit the issue to include this. Thanks!