DocsReferenceAPI reference
GET /v1/models
List models: the parameters, answers, errors and examples of GET /v1/models in the Rhumb API.
List models
Candidates for a task on given providers, with capabilities, current prices and quality scores.
- Retired and hidden offerings are left out unless include_retired or include_hidden is set.
- Counted.
Example: GET /v1/models?task=text.chat&providers=openrouter&limit=20
Parameters
| Name | In | Type | Description |
|---|---|---|---|
task | query | string | Only models for this task.Example: text.chat |
providers | query | string | Only offerings on these providers. Comma-separated.Example: openrouter |
needs | query | string | Only offerings with these capabilities. Comma-separated. |
include_retired | query | "true" | "false" | Include retired offerings (default false). |
include_hidden | query | "true" | "false" | Include offerings that are never recommended (default false). |
limit | query | string | Page size, 1–500 (default 100).Example: 20 |
offset | query | string | Models to skip (default 0). |
Responses
200body:ModelsListThe answer. Counts one call against the quota.
Headers:
RateLimit-Limit,RateLimit-Remaining,RateLimit-Reset,X-Quota-Limit,X-Quota-Remaining,X-Quota-Reset,X-Overage-Used,X-Overage-Limit400body:Errorinvalid_request (an unknown name or a malformed value:
fieldandallowedsay which) or key_in_query (keys go in a header, never the URL).Headers:
RateLimit-Limit,RateLimit-Remaining,RateLimit-Reset,X-Quota-Limit,X-Quota-Remaining,X-Quota-Reset,X-Overage-Used,X-Overage-Limitinvalid_request { "error": { "code": "invalid_request", "message": "Unknown task \"text.chit\"", "field": "task", "allowed": [ "text.chat", "text.embed" ] } }key_in_query { "error": { "code": "key_in_query", "message": "API keys are not accepted in the query string; send them in the Authorization header. Rotate a key that was put in a URL." } }401body:Errormissing_api_key (no key sent) or invalid_api_key (unknown, disabled, revoked or expired).
missing_api_key { "error": { "code": "missing_api_key", "message": "Send your API key as `Authorization: Bearer <key>`" } }invalid_api_key { "error": { "code": "invalid_api_key", "message": "The API key is not valid" } }403body:Erroraccount_suspended; insufficient_scope (the key lacks the scope the endpoint needs:
required_scopenames it); ip_not_allowed (the key's IP allowlist does not include the caller); wrong_key_kind (a management key, which calls only the key-management API); or (POST /v1/plan) decision_model_not_allowed:decision.model=jevis for internal accounts only.account_suspended { "error": { "code": "account_suspended", "message": "This account is suspended" } }insufficient_scope { "error": { "code": "insufficient_scope", "message": "This key lacks the `resolve` scope this endpoint needs", "required_scope": "resolve" } }ip_not_allowed { "error": { "code": "ip_not_allowed", "message": "This key may not be used from this IP address" } }wrong_key_kind { "error": { "code": "wrong_key_kind", "message": "Management keys only call the key-management API (/api/v1/manage); use a live or test key here" } }decision_model_not_allowed { "error": { "code": "decision_model_not_allowed", "message": "decision.model=jev is available to internal accounts only; use openai or local", "field": "decision.model", "allowed": [ "openai", "local" ] } }413body:Errorrequest_too_large: request bodies are limited to 64 KB.
request_too_large { "error": { "code": "request_too_large", "message": "Request bodies are limited to 64 KB" } }429body:Errorrate_limited (the per-minute rate; Retry-After says when to try again) or quota_exhausted (the period's calls are used up; no Retry-After,
resets_atandupgrade_urlinstead).Headers:
Retry-After,RateLimit-Limit,RateLimit-Remaining,RateLimit-Reset,X-Quota-Limit,X-Quota-Remaining,X-Quota-Reset,X-Overage-Used,X-Overage-Limitrate_limited { "error": { "code": "rate_limited", "message": "Rate limit of 10 requests a minute reached" } }quota_exhausted { "error": { "code": "quota_exhausted", "message": "Your plan's 1,000 calls for this period are used up", "resets_at": "2026-12-01T00:00:00.000Z", "upgrade_url": "https://rhumbdata.com/app/billing" } }