Overview
Model information endpointsAvailable Operations
- get - Get a model by its slug
- list - List all models and their properties
- count - Get total count of available models
- list_for_user - List models filtered by user provider preferences, privacy settings, and guardrails
get
Returns full details for a single model identified by its author and slug (e.g. openai/gpt-4). Supports variant suffixes (e.g. openai/gpt-4:free) and resolves known slug aliases.Example Usage
from openrouter import OpenRouter
import os
with OpenRouter(
http_referer="<value>",
x_open_router_title="<value>",
x_open_router_categories="<value>",
api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:
res = open_router.models.get(author="openai", slug="gpt-4")
# Handle response
print(res)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
author | str | ✔️ | The author/organization of the model | openai |
slug | str | ✔️ | The model slug, optionally including a variant suffix (e.g. gpt-4 or gpt-4:free) | gpt-4 |
http_referer | Optional[str] | ➖ | The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application. | |
x_open_router_title | Optional[str] | ➖ | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | ➖ | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
retries | Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
Response
components.ModelResponseErrors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.ForbiddenResponseError | 403 | application/json |
| errors.NotFoundResponseError | 404 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |
list
List all models and their propertiesExample Usage
from openrouter import OpenRouter
import os
with OpenRouter(
http_referer="<value>",
x_open_router_title="<value>",
x_open_router_categories="<value>",
api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:
res = open_router.models.list(offset=0, limit=500)
while res is not None:
# Handle items
res = res.next()
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
http_referer | Optional[str] | ➖ | The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application. | |
x_open_router_title | Optional[str] | ➖ | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | ➖ | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
offset | OptionalNullable[int] | ➖ | Number of records to skip for pagination. When both offset and limit are omitted, the full list is returned | 0 |
limit | Optional[int] | ➖ | Maximum number of records to return (max 1000). When both offset and limit are omitted, the full list is returned | 500 |
category | Optional[operations.GetModelsCategory] | ➖ | Filter models by use case category | programming |
supported_parameters | Optional[str] | ➖ | Filter models by supported parameter (comma-separated) | temperature |
output_modalities | Optional[str] | ➖ | Filter models by output modality. Accepts a comma-separated list of modalities (text, image, embeddings, audio, video, rerank, decisions, speech, transcription) or “all” to include all models. Defaults to “text”. | text |
sort | Optional[operations.GetModelsSort] | ➖ | Sort the returned models server-side. Prefer this over fetching the full list and sorting client-side. Options: pricing-low-to-high, pricing-high-to-low (average prompt/completion price), context-high-to-low (context length), throughput-high-to-low, latency-low-to-high (recent median performance), most-popular, top-weekly (tokens processed in the last week), newest (creation date), <index>-high-to-low for each Artificial Analysis index (the coding and agentic sorts are deprecated: Artificial Analysis has retired those indexes), design-arena-elo-high-to-low (best Design Arena ELO across arenas). Models without a score for the chosen benchmark are placed last. The decision sort ranks decision models, so pass output_modalities=decisions or all with it. When omitted, the existing default ordering is preserved. | newest |
q | Optional[str] | ➖ | Free-text search by model name or slug. | gpt-4 |
input_modalities | Optional[str] | ➖ | Filter models by input modality. Comma-separated list of: text, image, audio, file. | text,image |
endpoints | Optional[str] | ➖ | Filter models by the request API paths they serve, as listed in each model’s endpoints field. Comma-separated; a model must serve every listed path. Valid values: /api/v1/chat/completions, /api/v1/completions, /api/v1/messages, /api/v1/responses, /api/v1/embeddings, /api/v1/rerank, /api/alpha/decisions, /api/alpha/extractions, /api/v1/videos, /api/v1/audio/speech, /api/v1/audio/transcriptions, /api/v1/images, /api/v1/batches. When set without output_modalities, models of every output modality are considered (the companion /api/alpha/extractions route is served by text and decisions models alike). | /api/alpha/extractions |
context | Optional[int] | ➖ | Minimum context length (tokens). Models with smaller context are excluded. | 128000 |
min_price | OptionalNullable[float] | ➖ | Minimum prompt price in $/M tokens. | 0 |
max_price | OptionalNullable[float] | ➖ | Maximum prompt price in $/M tokens. | 10 |
arch | Optional[str] | ➖ | Filter models by architecture/model family (e.g. GPT, Claude, Gemini, Llama). | GPT |
model_authors | Optional[str] | ➖ | Filter models by the organization that created the model. Comma-separated list of author slugs. | openai,anthropic |
providers | Optional[str] | ➖ | Filter models by hosting provider. Comma-separated list of provider names. | OpenAI,Anthropic |
distillable | Optional[operations.Distillable] | ➖ | Filter by distillation capability. “true” returns only distillable models, “false” excludes them. | true |
zdr | Optional[operations.Zdr] | ➖ | When set to “true”, return only models with zero data retention endpoints. | true |
region | Optional[operations.Region] | ➖ | Filter to models with endpoints in the given data region (“eu” or “us”). | eu |
min_output_price | OptionalNullable[float] | ➖ | Minimum completion (output) price in $/M tokens. | 0 |
max_output_price | OptionalNullable[float] | ➖ | Maximum completion (output) price in $/M tokens. | 10 |
min_age_days | OptionalNullable[int] | ➖ | Minimum model age in days since its creation date. | 0 |
max_age_days | OptionalNullable[int] | ➖ | Maximum model age in days since its creation date. | 90 |
min_intelligence_index | OptionalNullable[float] | ➖ | Minimum Artificial Analysis Intelligence Index score (0-100); unscored models are excluded. | 50 |
max_intelligence_index | OptionalNullable[float] | ➖ | Maximum Artificial Analysis Intelligence Index score (0-100); unscored models are excluded. | 100 |
min_coding_index | OptionalNullable[float] | ➖ | ⚠️ DEPRECATED: This will be removed in a future release, please migrate away from it as soon as possible. Deprecated: Artificial Analysis has retired its Coding Index. Minimum score (0-100); unscored models are excluded. | 50 |
max_coding_index | OptionalNullable[float] | ➖ | ⚠️ DEPRECATED: This will be removed in a future release, please migrate away from it as soon as possible. Deprecated: Artificial Analysis has retired its Coding Index. Maximum score (0-100); unscored models are excluded. | 100 |
min_agentic_index | OptionalNullable[float] | ➖ | ⚠️ DEPRECATED: This will be removed in a future release, please migrate away from it as soon as possible. Deprecated: Artificial Analysis has retired its Agentic Index. Minimum score (0-100); unscored models are excluded. | 50 |
max_agentic_index | OptionalNullable[float] | ➖ | ⚠️ DEPRECATED: This will be removed in a future release, please migrate away from it as soon as possible. Deprecated: Artificial Analysis has retired its Agentic Index. Maximum score (0-100); unscored models are excluded. | 100 |
min_finance_and_accounting_index | OptionalNullable[float] | ➖ | Minimum Artificial Analysis Finance & Accounting Index score (0-100); unscored models are excluded. | 50 |
max_finance_and_accounting_index | OptionalNullable[float] | ➖ | Maximum Artificial Analysis Finance & Accounting Index score (0-100); unscored models are excluded. | 100 |
min_strategy_and_ops_index | OptionalNullable[float] | ➖ | Minimum Artificial Analysis Strategy & Ops Index score (0-100); unscored models are excluded. | 50 |
max_strategy_and_ops_index | OptionalNullable[float] | ➖ | Maximum Artificial Analysis Strategy & Ops Index score (0-100); unscored models are excluded. | 100 |
min_legal_index | OptionalNullable[float] | ➖ | Minimum Artificial Analysis Legal Index score (0-100); unscored models are excluded. | 50 |
max_legal_index | OptionalNullable[float] | ➖ | Maximum Artificial Analysis Legal Index score (0-100); unscored models are excluded. | 100 |
min_healthcare_and_medical_index | OptionalNullable[float] | ➖ | Minimum Artificial Analysis Healthcare & Medical Index score (0-100); unscored models are excluded. | 50 |
max_healthcare_and_medical_index | OptionalNullable[float] | ➖ | Maximum Artificial Analysis Healthcare & Medical Index score (0-100); unscored models are excluded. | 100 |
min_engineering_index | OptionalNullable[float] | ➖ | Minimum Artificial Analysis Engineering Index score (0-100); unscored models are excluded. | 50 |
max_engineering_index | OptionalNullable[float] | ➖ | Maximum Artificial Analysis Engineering Index score (0-100); unscored models are excluded. | 100 |
min_economics_index | OptionalNullable[float] | ➖ | Minimum Artificial Analysis Economics Index score (0-100); unscored models are excluded. | 50 |
max_economics_index | OptionalNullable[float] | ➖ | Maximum Artificial Analysis Economics Index score (0-100); unscored models are excluded. | 100 |
min_cyber_index | OptionalNullable[float] | ➖ | Minimum Artificial Analysis Cyber Index score (0-100); unscored models are excluded. | 50 |
max_cyber_index | OptionalNullable[float] | ➖ | Maximum Artificial Analysis Cyber Index score (0-100); unscored models are excluded. | 100 |
min_openness_index | OptionalNullable[float] | ➖ | Minimum Artificial Analysis Openness Index score (0-100); unscored models are excluded. | 50 |
max_openness_index | OptionalNullable[float] | ➖ | Maximum Artificial Analysis Openness Index score (0-100); unscored models are excluded. | 100 |
min_multilingual_index | OptionalNullable[float] | ➖ | Minimum Artificial Analysis Multilingual Index score (0-1); unscored models are excluded. | 0.5 |
max_multilingual_index | OptionalNullable[float] | ➖ | Maximum Artificial Analysis Multilingual Index score (0-1); unscored models are excluded. | 1 |
min_decision_index | OptionalNullable[float] | ➖ | Minimum Artificial Analysis Decision Index score (0-100); unscored models are excluded. | 50 |
max_decision_index | OptionalNullable[float] | ➖ | Maximum Artificial Analysis Decision Index score (0-100); unscored models are excluded. | 100 |
min_tool_success_rate | OptionalNullable[float] | ➖ | Minimum tool-calling success rate, as a fraction in [0, 1] (e.g. 0.9 = 90% of requests finishing with a tool_calls finish reason). | 0.9 |
max_tool_success_rate | OptionalNullable[float] | ➖ | Maximum tool-calling success rate, as a fraction in [0, 1]. | 1 |
retries | Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
Response
operations.GetModelsResponseErrors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.BadRequestResponseError | 400 | application/json |
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.ForbiddenResponseError | 403 | application/json |
| errors.NotFoundResponseError | 404 | application/json |
| errors.RequestTimeoutResponseError | 408 | application/json |
| errors.ConflictResponseError | 409 | application/json |
| errors.TooManyRequestsResponseError | 429 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.ServiceUnavailableResponseError | 503 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |
count
Get total count of available modelsExample Usage
from openrouter import OpenRouter
import os
with OpenRouter(
http_referer="<value>",
x_open_router_title="<value>",
x_open_router_categories="<value>",
api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:
res = open_router.models.count()
# Handle response
print(res)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
http_referer | Optional[str] | ➖ | The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application. | |
x_open_router_title | Optional[str] | ➖ | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | ➖ | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
output_modalities | Optional[str] | ➖ | Filter models by output modality. Accepts a comma-separated list of modalities (text, image, embeddings, audio, video, rerank, decisions, speech, transcription) or “all” to include all models. Defaults to “text”. | text |
retries | Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
Response
components.ModelsCountResponseErrors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.BadRequestResponseError | 400 | application/json |
| errors.ForbiddenResponseError | 403 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |
list_for_user
List models filtered by user provider preferences, privacy settings, and guardrails. Returns text-output models by default; passoutput_modalities (a comma-separated list of text, image, embeddings, audio, video, rerank, speech, transcription, or all) to include other modalities. If requesting through a regional hostname, the results will be filtered to models that satisfy in-region routing for that region.
Example Usage
from openrouter import OpenRouter, operations
import os
with OpenRouter(
http_referer="<value>",
x_open_router_title="<value>",
x_open_router_categories="<value>",
) as open_router:
res = open_router.models.list_for_user(security=operations.ListModelsUserSecurity(
bearer=os.getenv("OPENROUTER_BEARER", ""),
), offset=0, limit=500)
while res is not None:
# Handle items
res = res.next()
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
security | operations.ListModelsUserSecurity | ✔️ | N/A | |
http_referer | Optional[str] | ➖ | The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application. | |
x_open_router_title | Optional[str] | ➖ | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | ➖ | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
offset | OptionalNullable[int] | ➖ | Number of records to skip for pagination. When both offset and limit are omitted, the full list is returned | 0 |
limit | Optional[int] | ➖ | Maximum number of records to return (max 1000). When both offset and limit are omitted, the full list is returned | 500 |
output_modalities | Optional[str] | ➖ | Filter models by output modality. Accepts a comma-separated list of modalities (text, image, embeddings, audio, video, rerank, decisions, speech, transcription) or “all” to include all models. Defaults to “text”. | text |
sort | Optional[operations.ListModelsUserSort] | ➖ | Sort the returned models server-side. Prefer this over fetching the full list and sorting client-side. Options: pricing-low-to-high, pricing-high-to-low (average prompt/completion price), context-high-to-low (context length), throughput-high-to-low, latency-low-to-high (recent median performance), most-popular, top-weekly (tokens processed in the last week), newest (creation date), <index>-high-to-low for each Artificial Analysis index (the coding and agentic sorts are deprecated: Artificial Analysis has retired those indexes), design-arena-elo-high-to-low (best Design Arena ELO across arenas). Models without a score for the chosen benchmark are placed last. The decision sort ranks decision models, so pass output_modalities=decisions or all with it. When omitted, the existing default ordering is preserved. | newest |
client | Optional[operations.Client] | ➖ | Filter models and presets by the named harness’s eligibility policy: tool calling is required, and when one of your guardrails sets enforce_first_party_harness_models, only the harness vendor’s own models remain (OpenAI for codex, Anthropic for claude_code and claude_desktop). When your workspace’s Managed Machines policy sets a model list for that harness, only the listed models remain, and a preset remains only while every model it routes to is listed. This filter doesn’t apply the harness’s ranking, caps or Claude Desktop model ID aliases, so returned IDs stay routable. One of: claude_code, claude_desktop, codex. Omit it to get every model you can use. | codex |
retries | Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
Response
operations.ListModelsUserResponseErrors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.ForbiddenResponseError | 403 | application/json |
| errors.NotFoundResponseError | 404 | application/json |
| errors.RequestTimeoutResponseError | 408 | application/json |
| errors.ConflictResponseError | 409 | application/json |
| errors.TooManyRequestsResponseError | 429 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.ServiceUnavailableResponseError | 503 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |