OpenRouter APIopenrouter.ai ↗
Query OpenRouter's full AI model catalog: per-token prices, context lengths, provider endpoints, supported modalities, and generation settings via 3 endpoints.
What is the OpenRouter API?
This API exposes OpenRouter's AI model catalog across 3 endpoints, returning pricing, context limits, and per-provider configuration for approximately 520 models. The list_models endpoint pages through the full catalog with filters by category, returning USD per-token prices for prompt, completion, image, audio, cache read/write, and internal reasoning tokens. The get_model_endpoints endpoint drills into a single model's provider-level settings including quantization, tool-choice support, and max token limits.
curl -X GET 'https://api.parse.bot/scraper/3041f069-64ee-4b46-bdda-cce5a5e3351a/list_models?limit=3&category=programming' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace openrouter-ai-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: OpenRouter Models API — browse the catalog, drill into providers."""
from parse_apis.openrouter_ai_api import OpenRouter, ModelNotFound
client = OpenRouter()
# Browse programming models with pricing and reasoning info
for model in client.models.list(category="programming", limit=5):
print(model.name, model.modality, model.pricing)
if model.reasoning is not None:
print(" reasoning:", model.reasoning.default_effort, model.reasoning.mandatory)
# Drill down: pick the first model, then list its per-provider endpoints
model = client.models.list(limit=1).first()
if model is not None:
for provider in model.endpoints.list(limit=3):
print(provider.provider_name, provider.quantization, provider.pricing)
print(" tool choice auto:", provider.tool_choice.auto)
# Construct a model by known ID and fetch its provider endpoints
try:
for ep in client.model("prism-ml/ternary-bonsai-2-27b").endpoints.list(limit=2):
print(ep.endpoint_name, ep.uptime_last_1d)
except ModelNotFound as e:
print("model not found:", e.model_id)
# Fetch the full catalog snapshot with all models and their endpoints in one call
catalog = client.catalog.fetch()
print(f"Total models: {catalog.total} (text={catalog.counts.text}, image={catalog.counts.image}, video={catalog.counts.video})")
if catalog.models is not None:
first_model = catalog.models[0]
print(first_model.name, first_model.modality, first_model.pricing)
print("exercised: models.list / model() / endpoints.list / catalog.fetch")
Returns the full OpenRouter model catalog (one row per model, ~450 models) with USD per-token prices (prompt, completion, and where applicable image, audio, cache read/write, web search, internal reasoning), context length, modalities, tokenizer, the list of supported generation parameters, the model's default parameter values, reasoning settings, and top-provider limits. The whole catalog is fetched in one upstream call; offset/limit slice it locally, so paging costs nothing extra. Omitting offset starts at 0; omitting limit returns up to 500 models (the maximum, enough for the whole catalog). total is the catalog size for the chosen category filter; has_more tells whether another page exists. An optional category (an OpenRouter use-case category slug such as programming) narrows the list to models OpenRouter ranks for that category; unknown categories are passed to the site as-is. Prices are numbers in USD per single token (e.g. 5e-07 = $0.50 per million tokens).
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum number of models to return; values above 500 are clamped to 500. |
| offset | integer | Zero-based index of the first model to return within the catalog. |
| category | string | OpenRouter use-case category slug to filter models by (verified: programming). Omitted = whole catalog. |
{
"type": "object",
"fields": {
"limit": "integer, effective page size",
"total": "integer, number of models in the catalog (after category filter)",
"models": "array of model records; each has model_id (use with get_model_endpoints), canonical_slug, name, description, created (unix seconds), hugging_face_id, alias_target_slug (model_id this alias redirects to, null when not an alias), context_length, modality, input_modalities, output_modalities, tokenizer, instruct_type, pricing_usd_per_token (object of price components in USD per token, keys vary by model: prompt, completion, input_cache_read, input_cache_write, image, audio, web_search, internal_reasoning, ...), top_provider_context_length, top_provider_max_completion_tokens, top_provider_is_moderated, per_request_limits, supported_parameters (array of generation parameter names the model accepts), default_parameters (object of default values for those parameters, may be empty), reasoning (object with mandatory/default_enabled/supported_efforts/default_effort, null when not a reasoning model), supported_voices, knowledge_cutoff, expiration_date",
"offset": "integer, echoed start index",
"has_more": "boolean, true when offset+limit < total"
},
"sample": {
"data": {
"limit": 3,
"total": 446,
"models": [
{
"name": "PrismML: Ternary Bonsai 2 27B",
"created": 1789754046,
"modality": "text+image->text",
"model_id": "prism-ml/ternary-bonsai-2-27b",
"reasoning": {
"mandatory": false,
"default_effort": "xhigh",
"default_enabled": true,
"supported_efforts": [
"xhigh",
"medium"
]
},
"tokenizer": "Qwen",
"description": "Bonsai 2 27B is a 27B-parameter reasoning model from PrismML derived from Qwen3.8-27B.",
"instruct_type": null,
"canonical_slug": "prism-ml/ternary-bonsai-2-27b-20260918",
"context_length": 262144,
"expiration_date": null,
"hugging_face_id": "prism-ml/Ternary-Bonsai-2-27B-gguf",
"input_modalities": [
"text",
"image"
],
"knowledge_cutoff": null,
"supported_voices": null,
"alias_target_slug": null,
"output_modalities": [
"text"
],
"default_parameters": {
"top_k": 20,
"top_p": 0.95,
"temperature": 1
},
"per_request_limits": null,
"supported_parameters": [
"frequency_penalty",
"include_reasoning",
"logprobs",
"max_tokens",
"presence_penalty",
"reasoning",
"reasoning_effort",
"repetition_penalty",
"response_format",
"seed",
"stop",
"structured_outputs",
"temperature",
"tool_choice",
"tools",
"top_k",
"top_logprobs",
"top_p"
],
"pricing_usd_per_token": {
"prompt": 7.5e-8,
"completion": 5e-7
},
"top_provider_is_moderated": false,
"top_provider_context_length": 262144,
"top_provider_max_completion_tokens": 32768
}
],
"offset": 0,
"has_more": true
},
"status": "success"
}
}About the OpenRouter API
Model Catalog Access
The list_models endpoint returns up to 500 model records per call, each including a model_id (formatted as <author>/<slug>), display name, description, creation timestamp, modalities, tokenizer, and a full breakdown of USD per-token prices covering prompt, completion, image, audio, cache reads and writes, web search, and internal reasoning tokens. Use the optional category parameter to filter by OpenRouter use-case category (e.g., programming), and paginate with limit and offset. The response includes total, has_more, and offset fields to manage large result sets.
Per-Provider Endpoint Details
The get_model_endpoints endpoint accepts a model_id (exactly as returned from list_models) and returns the complete list of providers serving that model. Each provider entry in the endpoints array includes provider_name, endpoint_name, tag, quantization, context_length, max_completion_tokens, max_prompt_tokens, supported generation parameters, tool-choice support, and pricing with any applicable discount. Additional model-level fields include instruct_type, input_modalities, output_modalities, and modality (e.g., text+image->text).
Full Catalog in One Call
The list_models_full endpoint consolidates text, image, and video model catalogs into a single response of roughly 520 rows. Each record includes all per-provider endpoint data. The response also carries a counts object breaking down models by catalog type, a fetched_at UTC timestamp, and an errors array that surfaces any per-model or catalog-level fetch failures with stage, status_code, and message — useful for detecting partial data in automated pipelines.
The OpenRouter API is a managed, monitored endpoint for openrouter.ai — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when openrouter.ai changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official openrouter.ai API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Comparing prompt and completion token prices across all providers serving the same model using
get_model_endpoints. - Building a model-selection UI that filters OpenRouter's catalog by category and displays context length and modality from
list_models. - Monitoring quantization options and max completion token limits per provider to select the best inference configuration.
- Auditing cache read/write and internal reasoning token pricing across the full catalog via
list_models_full. - Tracking new model additions over time using the
createdunix timestamp field inlist_modelsresponses. - Identifying which providers support tool-choice for a given model before routing function-calling workloads.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does OpenRouter have an official developer API?+
What does `list_models_full` return that `list_models` does not?+
list_models_full combines text, image, and video model catalogs in one call and embeds per-provider endpoint data directly in each row, so you get the same detail as calling get_model_endpoints individually for every model. It also includes a counts breakdown by catalog type, a fetched_at timestamp, and an errors array that flags any models or catalogs that couldn't be fully retrieved. list_models returns the text catalog only and requires a separate get_model_endpoints call to get provider-level detail.What is the `limit` cap for `list_models`?+
offset parameter to paginate: check has_more in the response and increment offset by limit until has_more is false.Does the API return historical pricing or model deprecation data?+
Can I filter `list_models` by modality, tokenizer, or provider?+
list_models is category, which accepts an OpenRouter use-case category slug. Filtering by modality, tokenizer, or specific provider is not currently available at the endpoint level. You can fork this API on Parse and revise it to add those filter parameters against the returned fields.