Two read-only endpoints let scripts and tools answer "which models can I call?" and "how much do I have left?" without a browser session. Both use the same API key as inference and neither is billed.
List models with GET /v1/models#
curl https://tokens.bd/v1/models \
-H "Authorization: Bearer $TOKENS_API_KEY"{
"object": "list",
"data": [
{
"id": "deepseek/deepseek-v4.1-flash",
"object": "model",
"created": 1788000000,
"owned_by": "tokens",
"permission": [],
"root": "deepseek/deepseek-v4.1-flash",
"parent": null,
"name": "Claude Sonnet 5.5",
"context_length": 1000000,
"max_output_tokens": 64000,
"pricing": { "input": 3, "output": 15, "cache_read": 0.3, "cache_write": 3.75 },
"reasoning": true,
"reasoning_efforts": ["low", "medium", "high", "max"],
"pricing_bdt": { "input": 360, "output": 1800 },
"free_requests": { "limit": 50, "period": "day", "after_limit": "charge", "remaining": 38, "resets_at": "2026-11-17T18:00:00Z" }
}
]
}| Field | Meaning |
|---|---|
id | The exact string to send as model: provider/model, or a curated alias such as auto. |
object | Always "model". |
created | Unix timestamp of when the model was added to the catalog. |
owned_by | Always "tokens", whichever lab built the model. |
root, parent, permission | Present for OpenAI SDK compatibility; root equals id, or for a curated alias the model it serves now. |
name | The model's display name. For a curated alias, the alias and the model it serves now. |
context_length | The context window, in tokens. |
max_output_tokens | The most tokens one answer can have. |
pricing | What you pay in USD per 1M tokens: input, output, cache_read, cache_write. |
reasoning | true when the model reasons, false when it can't. |
reasoning_efforts | The effort levels the model takes, lowest first. Send one as reasoning_effort (or output_config.effort on /v1/messages). |
pricing_bdt | The same prices in taka per 1M tokens (input, output), as the site shows them. You are billed in USD. |
retires_at | When the model retires (ISO 8601). Requests answer until the operator switches it off, with deprecation headers. |
successor | The model to move to, when the retiring model has one in the catalog. |
free_requests | A free-access offer running on this model: limit requests a period, then after_limit (charge bills as usual, block refuses). remaining and resets_at are what your account has left. |
The fields after parent are left out when the catalog has no value for them, so treat a missing field as unknown. Code written for the plain OpenAI list keeps working, since every OpenAI field is unchanged. The model catalog has the same details, one page per model, including long-context prices. There are no flags for vision or tool calling: see Model catalog for how to find out what a model supports.
Curated aliases: auto and best-value#
When the platform offers them, names such as auto (a good default) and best-value are listed after the models. Send one as model and the gateway serves the model it points to today, chosen by the Tokens team. It is billed and recorded exactly as that model: its price, your plan's access to it, and the model name in your usage. The answer names the real model in its model field, and two headers say what happened:
| Header | Value |
|---|---|
x-tokens-model-alias | The curated name you sent, e.g. auto |
x-tokens-resolved-model | The model that served and was billed |
The model behind a curated alias can change. Pin a provider/model id when you need the same model every time. A key limited to certain models may call a curated alias when the model it points to is on the key's list.
Why a model is missing from the list#
The list is filtered for the key that calls it, so two keys on the same account can see different lists:
- Key allow-list. If the key was created with an allowed-models list, only those models appear.
- Plan and wallet. Each model is enabled for certain plan tiers and for pay-as-you-go. A model appears if your active plan's tier includes it, or if pay-as-you-go is allowed for it and your wallet balance is above zero.
- Catalog status. Only active catalog models are listed.
An empty data array usually means no active plan and no wallet balance. Subscribe or top up in billing; details in plans and wallet.
Check remaining usage with GET /v1/tokens/usage#
This endpoint is specific to Tokens. It returns the current plan, plan usage windows, wallet balance and the calling key's limits. The tokens.mjs usage CLI command reads it, and it's handy in a status bar or a pre-flight check in a long-running agent.
curl https://tokens.bd/v1/tokens/usage \
-H "Authorization: Bearer $TOKENS_API_KEY"{
"object": "tokens.usage",
"plan": {
"name": "Pro Monthly",
"tier": "monthly",
"periodEnd": "2026-11-02T08:15:00.000Z"
},
"windows": [
{
"type": "session_5h",
"label": "5-Hour Session",
"unit": "usd",
"limit": 5,
"used": 1.284,
"remaining": 3.716,
"percentUsed": 26,
"resetsAt": "2026-10-03T14:40:00.000Z"
}
],
"wallet": { "balanceUsd": 12.5 },
"key": {
"monthlySpendCapUsd": 20,
"allowedModels": null
},
"credits": { "budgetUsd": 70, "usedUsd": 17.5, "remainingUsd": 52.5, "availableUsd": 52.4 },
"owedUsd": 0,
"billingMode": "plan",
"status": { "state": "ok", "reason": "ok", "resumesAt": null },
"bonus": { "usd": 2, "expiresAt": "2026-12-01T00:00:00.000Z" },
"fx": { "usdBdt": 122 }
}The plan name and numbers above are illustrative; yours depend on your plan.
| Field | Type | Meaning |
|---|---|---|
plan | object or null | Active subscription, or null on pay-as-you-go only |
plan.tier | string | Plan tier, such as weekly or monthly |
plan.periodEnd | ISO 8601 or null | When the current subscription period ends |
windows[] | array | Plan usage windows that have usage in their current period |
windows[].type | string | session_5h (rolling 5 hours), weekly or monthly |
windows[].unit | string | usd (credits, expressed in USD) or requests |
windows[].limit, used, remaining | number | In the window's unit |
windows[].percentUsed | integer | 0 to 100 |
windows[].resetsAt | ISO 8601 | When the window resets |
wallet | object or null | balanceUsd: prepaid wallet balance in USD, or null if there is no wallet |
key.monthlySpendCapUsd | number or null | The calling key's monthly cap, null if uncapped |
key.allowedModels | array or null | The key's allow-list, null if any model is allowed |
credits | object or null | This period's plan credits in USD: budgetUsd, usedUsd, remainingUsd, and availableUsd (less what running requests hold). null without a plan |
owedUsd | number or null | Usage your plan and wallet couldn't cover; the next request or top-up repays it |
billingMode | string or null | What pays: plan, auto (the wallet once plan credits or a limit run out) or wallet |
status | object or null | state (ok, low, paused or out), reason, and resumesAt when requests pause until a time |
bonus | object or null | The usable sign-up bonus in USD (usd) and when it expires (expiresAt); it is part of wallet.balanceUsd |
fx.usdBdt | number | The rate tokens.bd shows taka at: taka = USD × usdBdt |
Note
A window that hasn't been used yet in its current period is left out of windows, so an empty array on a fresh plan or right after a reset is normal.
When a window is used up, inference requests return 429 window_exhausted until resetsAt. The dashboard can also notify you at 50, 75, 90 and 100 percent of a window; see usage and alerts.
The response is sent with Cache-Control: no-store. Polling it once a minute is plenty; it counts toward neither your bill nor your per-minute request limit.
Embeddings: POST /v1/embeddings#
The route exists and follows OpenAI's embeddings format, but it only works for catalog models that are embedding models. Chat models will fail on it. Check the model catalog for an embedding model before building on this endpoint; if none is listed, there is no embedding model available for your account yet.
Legacy completions: POST /v1/completions#
The old prompt-in, text-out completions endpoint is passed through for tools that still use it. It only works when the upstream behind a model supports it, and many chat models don't. Use chat completions for anything new.
Endpoints that don't exist#
Any other path under /v1 returns 404 with code unsupported_endpoint. That includes images, audio, files, batches, assistants, fine-tuning and moderations. See errors for the full code list.