Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

docs(api): document GET /v1/usage (#1615)

tashdroidd46195062ea5
diff --git a/docs/en/api/01-rest-api.md b/docs/en/api/01-rest-api.md
index 828553f3..8de6db2a 100644
--- a/docs/en/api/01-rest-api.md
+++ b/docs/en/api/01-rest-api.md
@@ -22,6 +22,7 @@ Any OpenAI-compatible client works (Anthropic / Claude clients too — see [Anth
- [Response headers](#response-headers)
- [Embeddings](#embeddings)
- [Anthropic / Claude clients](#anthropic--claude-clients)
+- [Usage API (`GET /v1/usage`)](#usage-api-get-v1usage)
- [Free-tier budget API](#free-tier-budget-api)
- [Backups API](#backups-api)
@@ -380,6 +381,40 @@ claude
> Use `ANTHROPIC_AUTH_TOKEN` (sent as a Bearer token), **not** `ANTHROPIC_API_KEY` — Claude Code treats a set `ANTHROPIC_API_KEY` as a conflicting first-party credential and refuses to start.
+## Usage API (`GET /v1/usage`)
+
+`GET /v1/usage` answers "what has this gateway actually burned this month?" from
+the durable `key_monthly_usage` ledger — the same numbers the monthly key caps
+enforce, so it never drifts from what a `429 quota_exceeded` was computed from.
+Authenticate with your unified proxy key (the same `Authorization: Bearer`
+every `/v1` route takes).
+
+```bash
+curl http://localhost:3001/v1/usage -H "Authorization: Bearer $FREELLMAPI_KEY"
+```
+
+```json
+{
+ "month": "2026-10",
+ "resetsAt": "2026-11-01T00:00:00.000Z",
+ "requests": 152,
+ "tokens": 104000000,
+ "byPlatform": [{ "platform": "opencode", "requests": 90, "tokens": 80000000 }],
+ "byKey": [
+ { "keyId": 3, "platform": "opencode", "label": "work laptop", "enabled": true,
+ "requests": 90, "tokens": 80000000, "requestCap": null, "tokenCap": 50000000 }
+ ]
+}
+```
+
+`byKey` is the per-provider-key breakdown — the row you need when one machine's
+agent config ate the month while the rest of the pool is untouched. `requestCap`
+/ `tokenCap` are the caps from [Monthly provider-key budgets](#monthly-provider-key-budgets)
+(`null` = unlimited); spend is **not** clamped at the cap, so a key can report
+above it — that is what trips the next request to `429`. Keys deleted since the
+month began report under platform `removed` with no caps. Only the **unified**
+proxy key may call this route; client-profile keys get `403`.
+
## Free-tier budget API
`GET /api/free-tier` returns the operator's free-tier budget as a **pool-deduped** monthly overview. Many models on one platform share the same free pool, so summing every model's label would double-count; the endpoint collapses models into quota pools (`inferQuotaPoolKey`) and reports **one documented budget per pool** (the largest `parseBudget` value seen in it), scaled by the number of usable (enabled + healthy/unknown) keys for the platform. Chain-disabled rows still contribute to a pool — they share the same provider allowance — and are only marked, never dropped, so the totals match the dashboard's stacked per-model bar.
diff --git a/docs/en/api/CHANGELOG.md b/docs/en/api/CHANGELOG.md
index 850b1b5f..9eebaeba 100644
--- a/docs/en/api/CHANGELOG.md
+++ b/docs/en/api/CHANGELOG.md
@@ -4,6 +4,10 @@
Doc revision history for `docs/api/`, seeded from API-relevant commits.
+## 2026-10-20
+
+- **docs(api): document `GET /v1/usage`** — the endpoint shipped with #1600 and gained a per-key breakdown in #1614 but was never in `01-rest-api.md`. Added a Usage API section: response shape (`month`, `resetsAt`, `requests`, `tokens`, `byPlatform[]`, `byKey[]` with `requestCap`/`tokenCap`, `null` = unlimited), unified-key-only auth (`403` for client profiles), deleted keys surfacing under platform `removed`, and the ledger-not-clamped-at-cap semantics that match `429 quota_exceeded`. Source: `server/src/routes/proxy.ts` (`GET /v1/usage` handler).
+
## 2026-09-03
- **docs(api): document the task-type routing header** — added `X-FreeLLM-Task-Type: code|chat|auto` (#1127) to the per-request headers section, with the weight shift it applies and the strategies that ignore it.