Search API fallback for AI agents with Mux

A search API fallback is an ordered list of search providers that a request walks through until one answers. In Mux you pass that list as models, up to five model ids, and the gateway tries each in order, refunds failed attempts and returns the first success along with an attempts array that shows what happened. An agent wired to a single provider stops when that provider has a bad minute; an agent with a fallback list keeps going and pays only for the model that answered.

Why one search provider is a single point of failure#

An agent that calls a web search tool in a loop depends on that tool in a way a human user never does. A person who sees an error retries in a few seconds. An agent mid-plan either crashes the run, hallucinates around the gap, or burns retries against a provider that is still down. The failure modes are ordinary:

• Provider 5xx. Every search API has outages and partial outages. During one, every request from your agent fails until the provider recovers.
• Rate limits. A burst of parallel tool calls, or a few agents sharing one provider key, can hit the provider's per-second or per-minute cap. Retrying harder makes it worse.
• Timeouts. A slow upstream turns a 1 second tool call into a 15 second one, and an agent framework with its own timeout gives up first.
• Regional problems. A provider can be fine from one region and unreachable from another.

The usual fix is to integrate two or three search APIs, write a retry wrapper, normalize three response shapes, and hold three billing relationships. Mux does that once, behind one endpoint, with one key and one bill. The response shape is identical no matter which provider answered, so your agent's parsing code does not change when the fallback kicks in.

How the models list works#

POST /v1/search accepts either model (one id) or models (an ordered list of up to five). When models is set it takes precedence. The rules:

If you omit both fields, Mux uses auto, which is a built-in fallback list: parallel/fast, then exa/auto, then keenable/pro. That order favors the cheapest model first and still covers all three providers.

The Mux SDKs retry 429 and 5xx responses twice with backoff, but not 502 all_providers_failed, because the gateway has already tried everything you allowed. That error is safe to retry yourself since you were not charged.

Recommended orders for three goals#

Prices below are list prices per 1,000 requests with 10 results each. See the live table on /pricing and the per-model pages such as /models/parallel/fast.

Cheapest first#

Start with parallel/fast at $1 per 1,000, fall back to keenable/pro at $4, and keep exa/auto at $7 as the last resort. Most requests cost $0.001, and the expensive model only runs when both cheaper ones are down.

Quality first#

Lead with exa/auto, which is Exa's general-purpose mode, then parallel/advanced for its high-quality excerpts, then keenable/pro. Use this for research agents where a weaker result set costs more in model tokens than the search does.

Note that content: "full" returns page text on Exa and joined excerpts on Parallel, but content is null on Keenable. If your agent needs page text, put Keenable last or leave it out.

Latency first#

For interactive agents, start with parallel/turbo at about 200 ms typical, then exa/instant at about 300 ms, then keenable/pro at about 700 ms.

A good rule for any order: put at least two different providers in the list. Two Exa variants protect you against a bad model, not against an Exa outage.

Reading attempts in your logs#

Log res.model and res.attempts on every search. A normal response has a single ok entry. A response that fell back looks like this:

Things to watch for:

• status: "error" means the provider was called and failed. It was refunded unless cost_usd is present, which marks a timeout that kept the base price.
• status: "skipped" means the model was never called. The error field says why, usually insufficient credits or a key limit. If you see this often, raise the key's limit or move a cheaper model earlier in the list.
• The last entry is always the model that served the request, and matches the top-level model field and the x-mux-model response header.
• A rising fallback rate for one provider is an early warning that it is degraded. Counting attempts entries with status: "error" by model over a window gives you a free provider health dashboard.

The same information appears per request on the activity page of the dashboard and from GET /v1/activity, where each failed upstream attempt is logged as its own row with its error.

FAQ#

Does a fallback cost more than a single-provider request?#

No. Each attempt's price is reserved before the call and refunded if it fails, so you pay for the model that succeeded. The one exception is a timed-out attempt, which keeps that model's base price because the provider has normally completed the search by then.

What happens if every model in the list fails?#

You get 502 all_providers_failed with the attempts array in the error body, and your balance is unchanged apart from any timed-out attempt. The SDKs do not retry this status automatically, but it is safe for you to retry.

Can I use models with my own provider keys?#

Yes. With BYOK, a request to a provider you have connected runs on your key, and attempts shows source: "byok" for it. If your key fails, Mux falls back to its own account for that provider at list price unless you set always_use: true.

How many models can I list?#

Up to five. Past three you get diminishing returns, since Mux currently routes to three providers. A list that covers all three providers is the strongest guard against an outage.

Set MUX_API_KEY and send your first fallback request in a minute with the quickstart.