Models & catalog

The catalog is the source of truth for which models BatchRouter can route to, what each one costs per provider, and which hosted tools it supports. Read it before you quote or submit a batch so you reference a model id that actually exists and matches your operation, region, and privacy needs.

GET /v1/catalog/models is public and requires no authentication — call it from anywhere, including the browser, to discover available models.

List the catalogCopy Anchor Link

The base call returns every model with its routing eligibility, context limits, and per-provider pricing.

curl https://api.batchrouter.com/v1/catalog/models

The response is { data: CatalogModel[], provider_count, pricing_updated_at }.

Filter the catalogCopy Anchor Link

Narrow the list with up to three query parameters. They combine with AND.

For example, list responses-capable models that can run web search:

curl "https://api.batchrouter.com/v1/catalog/models?operation=responses&hosted_tool=web_search"

What a model entry exposesCopy Anchor Link

Each CatalogModel describes the model once at the top level, then carries a provider_offerings array — one snapshot per provider that serves the model. The same model (for example, an open-weight model) can appear under several providers at different prices and in different regions; BatchRouter routes across all of them.

Top-level fields you'll use most:

• model — the model id you pass as model to quotes and batches (for example gpt-5.4-mini). It is the provider's own id for the model, so it can contain dots or slashes (meta-llama/Llama-3.3-70B-Instruct-Turbo).
• slug — a URL-safe form of the same model (gpt-5-4-mini), used only in the path of GET /v1/catalog/models/{slug}. Do not pass it as model.
• display_name, provider — human label and the primary provider slug.
• operations — the operation types this model supports (responses, embeddings, vision).
• context_window, max_input_tokens, max_output_tokens — token limits.
• input_modalities — accepted inputs (text, image, document, audio, video).
• supports_file_uploads, accepted_file_types, max_file_size — whether you can reference files from POST /v1/files, the MIME types accepted, and the max upload size in bytes.
• hosted_tools — the hosted tools available with this model (the same enum as the hosted_tool filter).
• is_available — whether the model is currently routable.

Each entry in provider_offerings is where per-provider routing detail lives:

• Pricing — price (per-provider, provider-declared rates). The top-level pricing_updated_at tells you how fresh the price data is.
• Capacity — capacity_status (active, draining, paused), available_queue_items, available_queue_tokens, and a capacity_freshness object (fresh / stale_heartbeat / unknown). Lanes marked stale_heartbeat are not treated as live routable supply.
• Regions — the offering's regions tags. For a provider that declares the countries it runs inference in, every offering carries the same tags, derived from those countries: the countries themselves, plus eu when all of them are EU members. BatchRouter publishes this metadata; it is not an enforced residency guarantee. The region_unavailable check does not read this per-offering field. It compares your allowed_regions with what the provider declares for itself: see Region matching.
• Data retention & privacy — retention_days, supports_zdr (zero data retention), data_collection (allow / deny), training_use, privacy_tiers, and privacy_terms_url.
• Hosted tools & files — hosted_tools, runtime_capabilities, accepted_file_types, supports_file_uploads.
• Status — status (active, paused, deprecated, disabled) and metadata_verification_status (verified / unverified / undeclared).

Trimmed exampleCopy Anchor Link

The shape below is illustrative and abridged — real responses contain more fields and many models. Always read live data from GET /v1/catalog/models; prices and capacity change frequently.

{
  "data": [
    {
      "slug": "gpt-5-4-mini",
      "model": "gpt-5.4-mini",
      "display_name": "GPT-5.4 mini",
      "provider": "openai",
      "operations": ["responses", "vision"],
      "context_window": 1000000,
      "max_output_tokens": 128000,
      "input_modalities": ["text", "image"],
      "supports_file_uploads": true,
      "accepted_file_types": ["image/*"],
      "hosted_tools": ["web_search"],
      "is_available": true,
      "provider_offerings": [
        {
          "provider": "openai",
          "provider_name": "OpenAI",
          "task_type": "responses",
          "context_window": 128000,
          "price": { "currency": "usd", "input_per_mtok": "0.15", "output_per_mtok": "0.60" },
          "capacity_status": "active",
          "regions": ["global"],
          "retention_days": 30,
          "supports_zdr": false,
          "hosted_tools": ["web_search"],
          "status": "active"
        }
      ]
    }
  ],
  "provider_count": 1,
  "pricing_updated_at": "2026-06-17T09:00:00Z"
}

Picking a modelCopy Anchor Link

BatchRouter accepts two ways to choose a model in a quote (POST /v1/quotes/model) or batch (POST /v1/batches):

The canonical item you'll quote against:

{"customer_item_id":"item-1","operation":"responses","model":"gpt-5.4-mini","input":{"messages":[{"role":"user","content":"Summarize: BatchRouter routes batch-AI workloads across providers."}]}}

Requiring hosted toolsCopy Anchor Link

If your workload needs a model that can call hosted tools, add required_tools to the quote or batch. BatchRouter only routes to lanes whose offering supports every requested tool; lanes that can't are returned with a tool_support rejection reason in quote_lanes.

{
  "models": ["gpt-5.4-mini", "claude-haiku-4-5"],
  "routing_mode": "cheapest",
  "required_tools": ["web_search", "python_execution"]
}

Valid tools are web_search, python_execution, calculator, time, file_search, and retrieval — the same set returned in each model's hosted_tools. To pre-filter the catalog to tool-capable models before you quote, combine required_tools with the catalog's hosted_tool query filter above.

Next stepsCopy Anchor Link