Count a chat request's input tokens
POST/v1/tokens/count
Counts a Chat Completions request's input tokens without calling a
model. Since 1.10.0. The body is a /v1/chat/completions body, so you
count exactly what you are about to send. Add a models list (up to
10) to compare the same request across models.
For each model the answer gives the input tokens; who counted them
(the provider routing picks, when it can count, else DVARA); the
vocabulary and where the tokens go; the context window DVARA holds the
request to and how much of it the input and max_tokens would use;
and the cost at DVARA's prices. Where DVARA has no price it answers
pricing_known: false, never a cost of zero. Prices need the
Enterprise platform.
The request is routed as a call would be. Workspace status, policy,
prompt templates, PII and guardrails run on it, because its text can go
to a provider to be counted. No model is called. No usage or cost is
recorded, and the count does not count against a call cap or the
unlicensed call band. A key with scopes needs completions:write.
A model that is refused gets an error entry while the others are
counted. When every model is refused (always so for a single model),
the first refusal is the answer, with the status a call would get.
Request
Responses
- 200
- 400
- 401
- 403
- 429
One count per model
The body is empty, not JSON or not an object; it has neither model nor models; models is not an array of names or names more than 10; or messages is empty (invalid_request). Also a refusal a call would get as 400, such as no_provider or pii_detected.
No key was sent (api_key_required), or the key is unknown (invalid_api_key), revoked (api_key_revoked) or expired (api_key_expired).
The key's nonempty scope list does not cover the operation (api_key_scope; chat, Responses, completions and the Cursor route need completions:write, embeddings need embeddings:write); a policy rule (policy_denied), guardrail (guardrail_blocked, hallucination_detected, grounding_unavailable), IP rule (ip_access_denied) or data-residency rule (data_residency_violation) refused the call; PII tokenization or redaction was needed but unavailable (pii_tokenize_unavailable, pii_redact_unavailable); or the workspace is suspended (workspace_suspended), over its cap (workspace_cap_exceeded), or must use its own provider credential (workspace_credential_required). A PII BLOCK is 400 pii_detected instead.
The key's rate limit is reached (rate_limit_exceeded, with a Retry-After header), priority admission control throttled the request (priority_throttled), or the provider is rate limiting the call (provider_rate_limited, with Retry-After when the provider gave one).
Response Headers
Seconds to wait before retrying, when known.