[Feature Request] Provide a Bearer-authenticated, real-time aggregated usage / quota API for third-party tools (e.g. CodexBar)

[Yuxin-Qiao]

Feature Request: Provide a Bearer-authenticated, real-time usage / quota aggregation API for third-party tools (e.g. CodexBar)

Submitted by: A DeepSeek API user + CodexBar (steipete/CodexBar) contributor
Use case: macOS menu-bar usage monitor + similar third-party tools across the ecosystem

---

TL;DR

Please expose a Bearer-authenticated, real-time, aggregated usage / quota endpoint under api.deepseek.com so tools like CodexBar can visualize DeepSeek consumption the way they already do for OpenAI Codex, Claude, Cursor, Gemini, etc.

This unlocks the entire third-party monitoring ecosystem for DeepSeek — power users who live in the terminal / menu bar / dashboards need a programmatic way to read their own consumption without opening a browser.

---

What I'm asking for

At minimum, an endpoint equivalent to OpenAI's Usage API in spirit. Reference fields:

Field	Why it matters
current_window_remaining_percent	5h rolling quota remaining (matches CodexBar's "session" bar)
current_window_resets_at	ISO 8601 reset timestamp
weekly_remaining_percent	weekly quota bar
weekly_resets_at	weekly reset
today_token_used	today token count
today_cost_usd	today cost (USD)
month_token_used	month token count
month_cost_usd	month cost (USD)
last_refresh_at	for cache / staleness checks

Standard Authorization: Bearer <api_key> should work — no session cookies, no CSRF, no web login flow.

---

Why — what's blocking us today

1. https://api.deepseek.com/user/balance is Bearer-authenticated, but only returns the cash balance, not token / cost breakdowns.
2. https://platform.deepseek.com/api/v0/usage/amount and /usage/cost are exactly what third-party tools need — but they live under the web console domain and only authenticate via session cookies, not Bearer. From an API key's perspective, they return HTTP 200 + {"code": 40003, "msg": "Authorization Failed"} — a successful-looking response with an application-level error that is very easy to miss.
3. The per-request usage field from /chat/completions only gives per-call data, not aggregated dashboards.
4. The web dashboard has noticeable delay; users have no real-time channel to monitor their own consumption.

---

Concrete user impact — the bug my PR hit

I previously submitted CodexBar PR #1166 (92598f8d feat: add DeepSeek usage summaries, merged into v0.32.2) implementing a DeepSeekAPIFetchStrategy against the platform.deepseek.com usage endpoints with Bearer auth. The PR was merged in good faith — but in practice, the dashboard silently shows "balance only" for 100% of Bearer-authenticated users because:

1. The fetcher's guard response.statusCode == 200 else { throw } is satisfied (status IS 200).
2. The parser sees data: null → throws parseFailed("Missing amount biz_data").
3. completedOptionalUsageSummary discards the error silently inside a 2s grace window.
4. The UI sees snapshot?.deepSeekUsage == nil and hides the whole dashboard section.

There is no telemetry, no log line, and no UI hint to surface this failure to the user — every layer swallows the error. So end users think "CodexBar's DeepSeek integration just doesn't have a usage breakdown feature", when in reality the API server is rejecting every call.

If DeepSeek exposes a Bearer-authenticated real-time endpoint, the CodexBar fix becomes trivial: swap the strategy from cookie-style to Bearer-style. I (the PR author) am happy to send the fix immediately.

---

Suggested endpoint shape (sketch)

GET https://api.deepseek.com/v1/usage
Authorization: Bearer <api_key>

200 OK
{
  "balance_usd": "12.34",
  "today": {
    "prompt_tokens": 1234567,
    "completion_tokens": 234567,
    "total_tokens": 1469134,
    "cost_usd": "3.21"
  },
  "month": { "...": "..." },
  "current_window": {
    "remaining_percent": 78.5,
    "resets_at": "2026-06-09T03:00:00Z"
  },
  "weekly": { "...": "..." },
  "last_refresh_at": "2026-06-08T23:30:00Z"
}

A one-team / one-sprint change that unlocks CodexBar, Hammerspoon scripts, Slack bots, Prometheus exporters, etc.

---

Reference

• CodexBar repo: https://github.com/steipete/CodexBar
• CodexBar DeepSeek provider: Sources/CodexBarCore/Providers/DeepSeek/
• My previous PR (merged but silently broken for all Bearer users): #1166 in steipete/CodexBar
• OpenAI Usage API for reference: https://platform.openai.com/usage
• DeepSeek API docs: https://api-docs.deepseek.com/

---

Thanks for the great models — looking forward to seeing usage visibility improve. Happy to collaborate on the CodexBar side as soon as the endpoint is live.

[Yuxin-Qiao]

📌 Follow-up: a concrete feature CodexBar wants to ship once the API is available (2026-06-08)

As a contributor to CodexBar (@steipete/CodexBar), I want to share one very concrete thing CodexBar can ship the moment DeepSeek exposes the endpoint.

What I want to add to CodexBar's DeepSeek provider

Per-model cost / token breakdown view. DeepSeek's own web dashboard already splits by model (e.g. deepseek-v4-flash listed separately, with prompt / completion / cache-hit / cache-miss token counts). CodexBar can mirror that exact layout — one row per model:

deepseek-v4-flash
  Requests:    1,204
  Tokens:      102,414,387 (cache hit 100.5M / miss 1.3M / output 655K)
  Cost:        $0.62

deepseek-chat
  Requests:    230
  Tokens:      5,234,112
  Cost:        $0.02

deepseek-reasoner
  Requests:    5
  Tokens:      87,000
  Cost:        $0.00

Zero learning curve for users migrating from the web dashboard to the menu bar.

Why I can't ship this today

I previously submitted CodexBar PR #1166 (92598f8d feat: add DeepSeek usage summaries, merged into v0.32.2) using Bearer auth against platform.deepseek.com/api/v0/usage/amount and /cost. It silently fails for 100% of Bearer-authenticated users (3 layers of error-swallowing, UI shows nothing — issue #885 in CodexBar is still tracking this).

Fields needed (per-model breakdown view)

Field	Notes
model_id	e.g. deepseek-v4-flash / deepseek-chat / deepseek-reasoner
prompt_tokens	total input tokens
prompt_cache_hit_tokens	cache hits (DeepSeek already exposes this on the platform)
prompt_cache_miss_tokens	cache misses
completion_tokens	output tokens
total_tokens	sum
cost_usd or cost_cny	per-model cost subtotal
time_window	today / month / current 5h window

Derived metrics (computed client-side, no extra fields needed)

Once CodexBar has the raw fields, it can derive a whole analytics layer — DeepSeek doesn't need to expose anything new:

• Cache hit rate = prompt_cache_hit_tokens / (hit + miss) — reflects cache effectiveness
• Cache savings = cache_hit_tokens × (input_price − cache_hit_price) — how much money the cache saved
• Average tokens per request = total_tokens / request_count — prompt bloat check
• Input / output ratio = prompt_tokens / completion_tokens — input-heavy vs output-heavy workloads
• Per-model cost share = model_cost / total_cost — where the money goes
• Per-model hit-rate ranking — which models are cache-friendly
• Daily trend (per model) — is usage concentrating into a particular model?

If DeepSeek also exposes a time_window field (today / week / month / custom), this view becomes a 1:1 mirror of the platform dashboard.

Ship commitment

If DeepSeek exposes a Bearer-authenticated real-time usage API with per-model breakdown, I (PR #1166's author) can ship two PRs back-to-back:

1. PR-A: Switch the existing DeepSeekAPIFetchStrategy from cookie-style to Bearer-style — fixes the 100% silent-failure on Bearer users.
2. PR-B: Add the per-model cost / token view (the layout above) to CodexBar's DeepSeek provider.

End-to-end experience matching OpenAI Codex in CodexBar, shippable within a week of the endpoint going live. Concrete scenario, concrete ship commitment.