/openrouter/models/search

POST /api/openrouter/models/search

Price: 1 credit

Search the OpenRouter model catalogue

How to use it

Use this to shortlist models by capability, price or benchmark score before asking for one model's hosting details. A model that sells several billing variants comes back once per variant, so the same `alias` can appear twice with a different `id` and price. The price bounds are USD per 1M tokens and only constrain the default endpoint, which is one provider out of several — pass the model to /openrouter/models/endpoints for the full spread. `authors` takes the segment before the slash in an alias, so 'openai' for 'openai/gpt-4o'.

Parameters

• access-token string required

Request body

• timeout integer — Max scrapping execution timeout (in seconds) (default: 300; min: 20; max: 1500)
• q string nullable — Free-text query matched against model name and description (examples: "claude")
• authors array nullable — Restrict to these model authors, by the author segment of the model alias (examples: ["openai","anthropic"])
• series array nullable — Restrict to these model series (one of: "Other", "GPT", "Mistral", "Gemini", "Llama3", "Qwen", "Qwen3", "Claude", "Grok", "DeepSeek", "Llama2", "Router", "Cohere", "Yi", "Media", "Gemma", "Nova", "PaLM", "Llama4", "RWKV"; examples: ["Claude"])
• use_cases array nullable — Restrict to models ranked in these usage categories (one of: "academia", "finance", "health", "legal", "marketing", "marketing/seo", "programming", "roleplay", "science", "technology", "translation", "trivia"; examples: ["programming"])
• input_modalities array nullable — Restrict to models accepting all of these input modalities (one of: "text", "image", "file", "video", "audio"; examples: ["image"])
• output_modalities array nullable — Restrict to models producing all of these output modalities (one of: "text", "image", "embeddings", "video", "transcription", "speech", "rerank", "audio"; examples: ["video"])
• variant string nullable — Restrict to a billing variant of the default endpoint (one of: "standard", "batch", "free")
• providers array nullable — Restrict to models served by at least one of these providers (one of: "AI21", "AionLabs", "AkashML", "Alibaba", "Amazon Bedrock", "Amazon Nova", "Ambient", "Anthropic", "Arcee AI", "AtlasCloud", "Avian", "Azure", "Baidu", "BaseTen", "Black Forest Labs", "Cerebras", "Chutes", "Cirrascale", "Clarifai", "Claude Platform on AWS", "Cloudflare", "Cohere", "CoreWeave", "Cosine", "Crucible", "Crusoe", "Darkbloom", "Databricks", "Decart", "Deepgram", "DeepInfra", "DeepSeek", "DekaLLM", "DigitalOcean", "FakeProvider", "Featherless", "Fireworks", "Fish Audio", "Friendli", "GMICloud", "Google AI Studio", "Google", "Groq", "HeyGen", "Inception", "Inceptron", "Inferact vLLM", "InferenceNet", "Infermatic", "Inflection", "Io Net", "Ionstream", "Krea", "Liquid", "Makora", "Mancer 2", "Mara", "Meta", "Minimax", "Mistral", "Modal", "ModelRun", "Modular", "Moonshot AI", "Morph", "Nebius", "Nex AGI", "NextBit", "Novita", "Nvidia", "Ollama", "OpenAI", "OpenInference", "Parasail", "Perceptron", "Perplexity", "Phala", "Poolside", "PrimeIntellect", "Quiver", "Recraft", "Reka", "Relace", "Runway", "Sail Research", "Sakana AI", "SambaNova", "Seed", "SiliconFlow", "Sourceful", "xAI", "Stealth", "StepFun", "StreamLake", "Switchpoint", "Tencent", "Tenstorrent", "Thinking Machines", "Together", "Upstage", "Venice", "VoyageAI by MongoDB", "Wafer", "Xiaomi", "Z.AI"; examples: ["Anthropic"])
• supported_parameters array nullable — Restrict to models whose endpoints accept these request parameters (one of: "max_tokens", "temperature", "response_format", "top_p", "seed", "structured_outputs", "tools", "tool_choice", "stop", "reasoning", "include_reasoning", "frequency_penalty", "presence_penalty", "top_k", "repetition_penalty", "logprobs", "top_logprobs", "logit_bias", "min_p", "max_completion_tokens", "verbosity", "web_search_options", "prediction", "reasoning_effort", "parallel_tool_calls", "top_a"; examples: ["tools"])
• region string nullable — Restrict to models with an endpoint hosted in this region (one of: "eu", "us")
• min_context_length integer nullable — Minimum context window, in tokens (examples: 200000; min: 0)
• min_input_price number nullable — Minimum prompt price, USD per 1M tokens (examples: 5; min: 0)
• max_input_price number nullable — Maximum prompt price, USD per 1M tokens; 0 keeps only free prompts (examples: 1; min: 0)
• min_output_price number nullable — Minimum completion price, USD per 1M tokens (examples: 10; min: 0)
• max_output_price number nullable — Maximum completion price, USD per 1M tokens (examples: 1; min: 0)
• min_age_days integer nullable — Minimum number of days since the model was published (examples: 365; min: 0)
• max_age_days integer nullable — Maximum number of days since the model was published (examples: 30; min: 0)
• min_intelligence_index number nullable — Minimum Artificial Analysis intelligence index (examples: 40; min: 0)
• max_intelligence_index number nullable — Maximum Artificial Analysis intelligence index (examples: 10; min: 0)
• min_coding_index number nullable — Minimum Artificial Analysis coding index (examples: 50; min: 0)
• max_coding_index number nullable — Maximum Artificial Analysis coding index (examples: 10; min: 0)
• min_agentic_index number nullable — Minimum Artificial Analysis agentic index (examples: 30; min: 0)
• max_agentic_index number nullable — Maximum Artificial Analysis agentic index (examples: 5; min: 0)
• min_tool_success_rate number nullable — Minimum tool-call success rate, 0 to 1 (examples: 0.9; min: 0; max: 1)
• max_tool_success_rate number nullable — Maximum tool-call success rate, 0 to 1 (examples: 0.2; min: 0; max: 1)
• arena_category string nullable — Design Arena category the Elo bounds below apply to (one of: "image", "3d", "codecategories", "dataviz", "gamedev", "uicomponent", "svg")
• min_arena_elo number nullable — Minimum Design Arena Elo in arena_category (examples: 1200; min: 0)
• max_arena_elo number nullable — Maximum Design Arena Elo in arena_category (examples: 1100; min: 0)
• is_distillable boolean nullable — True keeps only distillable models, false keeps only non-distillable ones
• zero_data_retention_only boolean — Keep only models with a zero-data-retention endpoint (default: false)
• hipaa_eligible_only boolean — Keep only models with a HIPAA-eligible endpoint (default: false)
• discounted_only boolean — Keep only models currently discounted (default: false)
• active_only boolean — Keep only models that are currently serving traffic (default: false)
• order string nullable — Result ordering; omitted returns the newest first (one of: "most-popular", "newest", "oldest", "top-weekly", "weekly-tokens-low-to-high", "discount-high-to-low", "pricing-low-to-high", "pricing-high-to-low", "context-high-to-low", "context-low-to-high", "throughput-high-to-low", "throughput-low-to-high", "latency-low-to-high", "latency-high-to-low", "intelligence-high-to-low", "intelligence-low-to-high", "coding-high-to-low", "coding-low-to-high", "agentic-high-to-low", "agentic-low-to-high", "da-elo-high-to-low", "da-elo-low-to-high")
• count integer required — Max result count (min: 1)

Response

• @type string (default: "OpenrouterModel")
• id string required
• alias string required
• url string required
• variant string nullable
• version_alias string nullable
• name string nullable
• short_name string nullable
• description string nullable
• author string nullable
• author_display_name string nullable
• author_image string nullable
• author_flagship_modalities array (default: [])
• huggingface_id string nullable
• huggingface_updated_at string nullable
• family string nullable
• version_group_id string nullable
• context_length integer nullable
• input_modalities array (default: [])
• output_modalities array (default: [])
• has_text_output boolean nullable
• is_hidden boolean nullable
• is_private boolean nullable
• is_trainable_text boolean nullable
• is_trainable_image boolean nullable
• supports_reasoning boolean nullable
• reasoning_config object (default: {})
• features object (default: {})
• default_parameters object (default: {})
• default_order array (default: [])
• default_stops array (default: [])
• default_system string nullable
• instruct_type string nullable
• quick_start_example_type string nullable
• router string nullable
• warning_message string nullable
• promotion_message string nullable
• routing_error_message string nullable
• required_attestation_types array (default: [])
• display_required_attestation_types array (default: [])
• supported_tts_voices array (default: [])
• previews_by_modality object (default: {})
• thumbnail string nullable
• preview_audio object (default: {})
• limit_rpm integer nullable
• limit_rpd integer nullable
• knowledge_cutoff_at string nullable
• created_at string nullable
• updated_at string nullable
• intelligence_index number nullable
• coding_index number nullable
• agentic_index number nullable
• default_arena_elo number nullable
• arena_elo_by_category object (default: {})
  • * number
• endpoint object nullable
  • @type string (default: "OpenrouterModelEndpoint")
  • id string required
  • name string nullable
  • model_alias string nullable
  • model_version_alias string nullable
  • provider object nullable
    • @type string (default: "OpenrouterProvider")
    • alias string required
    • name string nullable
    • display_name string nullable
    • adapter_name string nullable
    • base_url string nullable
    • headquarters string nullable
    • datacenters array (default: [])
    • has_chat_completions boolean nullable
    • has_completions boolean nullable
    • is_abortable boolean nullable
    • is_moderation_required boolean nullable
    • is_byok_enabled boolean nullable
    • sends_client_ip boolean nullable
    • pricing_strategy string nullable
    • required_attestation_types array (default: [])
    • status_page_url string nullable
    • image string nullable
    • data_policy object nullable
      • @type string (default: "OpenrouterDataPolicy")
      • is_training boolean nullable
      • is_training_openrouter boolean nullable
      • is_retaining_prompts boolean nullable
      • retention_days integer nullable
      • can_publish boolean nullable
      • requires_user_ids boolean nullable
      • terms_url string nullable
      • privacy_url string nullable
  • provider_name string nullable
  • provider_model_id string nullable
  • provider_region string nullable
  • adapter_name string nullable
  • variant string nullable
  • quantization string nullable
  • context_length integer nullable
  • max_prompt_tokens integer nullable
  • max_completion_tokens integer nullable
  • max_tokens_per_image integer nullable
  • capacity_tpm integer nullable
  • limit_rpm integer nullable
  • limit_rpd integer nullable
  • status integer nullable
  • is_free boolean nullable
  • is_hidden boolean nullable
  • is_private boolean nullable
  • is_byok boolean nullable
  • is_byok_only boolean nullable
  • is_deranked boolean nullable
  • is_disabled boolean nullable
  • is_hipaa_eligible boolean nullable
  • is_pricing_unresolved boolean nullable
  • is_moderation_required boolean nullable
  • can_abort boolean nullable
  • supports_reasoning boolean nullable
  • supports_tool_parameters boolean nullable
  • supports_multipart boolean nullable
  • has_chat_completions boolean nullable
  • has_completions boolean nullable
  • supported_parameters array (default: [])
  • excluded_parameters array (default: [])
  • allowed_passthrough_parameters array (default: [])
  • supported_image_parameters object (default: {})
  • supported_video_parameters object (default: {})
  • features object (default: {})
  • data_policy object nullable
    • @type string (default: "OpenrouterDataPolicy")
    • is_training boolean nullable
    • is_training_openrouter boolean nullable
    • is_retaining_prompts boolean nullable
    • retention_days integer nullable
    • can_publish boolean nullable
    • requires_user_ids boolean nullable
    • terms_url string nullable
    • privacy_url string nullable
  • pricing object nullable
    • @type string (default: "OpenrouterEndpointPricing")
    • prompt number nullable
    • completion number nullable
    • input_cache_read number nullable
    • input_cache_write number nullable
    • image number nullable
    • image_output number nullable
    • image_token number nullable
    • request number nullable
    • web_search number nullable
    • internal_reasoning number nullable
    • discount number nullable
    • audio number nullable
    • input_audio_cache number nullable
    • input_cache_write_1h number nullable
    • raw object (default: {})
    • display_prices array (default: [])
      • @type string (default: "OpenrouterPriceItem")
      • kind string nullable
      • label string nullable
      • price number nullable
      • unit_label string nullable
      • display_multiplier number nullable
      • tiers array (default: [])
      • is_server_tool boolean nullable
      • is_discount_exempt boolean nullable
      • schedule_windows array (default: [])
  • pricing_version_id string nullable
  • stats object nullable
    • @type string (default: "OpenrouterEndpointStats")
    • latency_metric string nullable
    • p50_latency number nullable
    • p75_latency number nullable
    • p90_latency number nullable
    • p95_latency number nullable
    • p99_latency number nullable
    • p50_throughput number nullable
    • p75_throughput number nullable
    • p90_throughput number nullable
    • p95_throughput number nullable
    • p99_throughput number nullable
    • latency_request_count integer nullable
    • throughput_request_count integer nullable
    • request_count integer nullable
    • window_minutes integer nullable
  • uptime array (default: [])
    • @type string (default: "OpenrouterUptimePoint")
    • date string required
    • uptime number nullable
  • p50_latency number nullable
  • p50_throughput number nullable
  • created_at string nullable
  • deprecation_date string nullable
• usage object nullable
  • @type string (default: "OpenrouterModelUsage")
  • date string nullable
  • variant string nullable
  • request_count integer nullable
  • prompt_token_count integer nullable
  • completion_token_count integer nullable
  • reasoning_token_count integer nullable
  • cached_token_count integer nullable
  • tool_call_count integer nullable
  • tool_call_error_request_count integer nullable
  • media_prompt_count integer nullable
  • media_completion_count integer nullable
  • audio_prompt_count integer nullable
  • video_prompt_count integer nullable
  • image_output_request_count integer nullable
  • video_output_seconds number nullable
  • rerank_document_count integer nullable
  • transcript_character_count integer nullable
• category_usage array (default: [])
  • @type string (default: "OpenrouterCategoryUsage")
  • category string required
  • date string nullable
  • rank integer nullable
  • volume number nullable
  • request_count integer nullable
  • prompt_token_count integer nullable
  • completion_token_count integer nullable

Errors

• 422 — The request body did not validate Check the fields against this schema. A URN with the wrong prefix is the most common cause.
• 408 — The request ran past its time limit Raise `timeout` in the request body, up to the maximum this endpoint documents. Lowering `count` or turning off the `with_*` flags also helps, because less work finishes sooner.
• 412 — The entity was not found, or a precondition failed Retrying will not help: either the entity does not exist, or the input points at a different one.
• 429 — Too many requests: a rate limit or a usage window is exhausted When the response carries an X-Retry-After header, wait that many seconds and retry: the same number is in the body as `detail.retry_after`, and the limit clears once that window passes. The message in the body names the limit that was hit.
• 500 — Something broke on our side Retrying will not help. If it keeps happening, send us the X-Request-ID from the response headers.
• 529 — Rate limit reached, or the endpoint is overloaded Wait at least 30 seconds, then retry.

Response headers

• X-Error — Error message text (present only on error)
• X-Request-ID — Unique request identifier
• X-Execution-Time — Execution time in seconds
• X-Result-Count — How many records the body carries. 0 means an empty result, which is a normal answer and not by itself an error. A non-zero count can come back together with X-Error when the failure happened partway through — read this header and X-Error independently.
• X-Total-Available-Results — How many records exist for this query, when the endpoint can say. On a `dry_run` request this is the answer and the body is empty. It saturates: the endpoint's documented maximum means 'at least that many', any smaller number is exact.
• X-Warning — Present when the request body carried keys this endpoint does not document. They were ignored, so any filter you meant to apply through them did not apply. Check the spelling against this schema and retry.
• X-Retry-After — Seconds to wait before retrying. Present only on 429.