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.mdindex 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.mdindex 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.