Repository navigation
API: let API-key and Proxy users read their usage (GET /v1/usage) #1479
Description
Summary
Let API-key and Maple Proxy users read their account's usage from the API, so they can check it from scripts and tools without opening the app.
Why
A user who works with Maple mostly through Maple Proxy asked for a usage endpoint. Settings → Usage now shows plan credits, pace, daily credits by model and recent requests. Today that data is only available to a signed-in app session. The page loads it with a session-derived token (apps/maple-research/frontend/src/billing/usageApi.ts), so an API key can't read it.
API users can already get token counts for individual requests from the usage field in API responses. They can't get credits charged, plan credits remaining, the reset date or totals over time.
Proposal
A read-only endpoint that accepts the same credentials as the rest of the API, an API key or a session token:
GET /v1/usagereturns the current billing period (plan credits used, allowance, reset date, Extra credits balance) and a summary for a range (credits, requests, tokens, by day and model). It mirrors what Settings → Usage shows.- Optionally,
GET /v1/usage/requestsreturns recent requests, paginated. - Maple Proxy exposes the same route, so
GET http://localhost:8080/v1/usageworks with the configured key.
What already exists
- Credentials: API routes already accept an API key or a session token and resolve it to the account (
services/opensecret/src/web/openai_auth.rs). - Billing calls: OpenSecret already calls the billing service for account usage checks (
services/opensecret/src/billing.rs). - Proxy routing: Maple Proxy forwards OpenAI-compatible routes one by one (
proxy/src/lib.rs), so adding a route is small. - Response shape: the Usage page's data types are a reasonable starting point (
usageApi.ts).
Open questions
- Scope: should an API key see the whole account's usage, or only usage made with that key? Per-key tracking is API keys: per-key spend tracking and user-set budgets #1139.
- Contract: what should the response shape and versioning be? Once people script against it, it's a public contract.
- Rate limits: what limit and caching suit the endpoint?
- Teams: what should a Team member's key return: their own usage, the shared pool, or both?
Related
- API keys: per-key spend tracking and user-set budgets #1139 API keys: per-key spend tracking and user-set budgets
- API keys: show when each key was last used #1138 API keys: show when each key was last used
Activity
bennyhodl commentedon Nov 6, 2026
🤖 Claude Opus 5.5 responding on behalf of bennyhodl
Thanks for opening this. Here's the concrete use case behind the request.
I run Maple Proxy behind CLIProxyAPI, which routes my coding tools (Claude Code, Codex, Pi, OpenCode, T3 Code) to several providers, Maple among them. T3 Code reads subscription limits from CLIProxyAPI and shows one bar per provider: how much is left and when it resets. I'd like Maple to show up there next to the others.
What would make that work:
GET /v1/usage, and the same route on Maple Proxy.CLIProxyAPI reads quotas as a plan name plus buckets, each with a
remainingFraction(0–1) and aresetTime. If/v1/usageincludes the current period in that shape, it plugs in with no mapping:{ "subscription": { "plan": "Pro" }, "groups": [{ "displayName": "Plan credits", "buckets": [{ "window": "billing period", "remainingFraction": 0.62, "resetTime": "2026-12-01T00:00:00Z" }] }] }Field reference:
QuotaFetchResponsein CLIProxyAPI. For a ready-made integration, Maple could also publish a quota plugin to the CLIProxyAPI plugin store (plugin docs).Longer term, and lower priority: Maple as an OAuth login in CLIProxyAPI, next to Codex and Claude, would be the cleanest setup, with quota built in and no keys to paste. It would also be good branding for Maple, since it would sit in the login list with the big providers. The endpoint above already covers what I need.