Search the web

Web search answers a question from the current web and returns the source links it used. It runs on the same Flux key as your chat requests and is billed to the same account. It is a paid ability.

To read one page you already know, use Read a web page instead.

Two ways to search#

• Standalone. Your agent calls the web_search tool, or your code sends POST /v1/search with a query. You get back a written answer and its sources. Use this when you want the answer itself, or the links to read next.
• Inside a chat request. Send a normal POST /v1/chat/completions to flux-auto, flux-fast, flux-standard or flux-reasoning, and Flux routes it to a model that can search when the request asks for it. Use this when search is one step in a conversation.

Search from your agent or your code#

Add the Flux tools server once, and your agent gets a web_search tool that takes a query. From your own code, send the query to POST /v1/search.

claude mcp add --transport http flux-tools https://api.fluxrouter.ai/mcp-tools/ \
  --header "Authorization: Bearer sk-YOUR-FLUX-KEY"

[mcp_servers.flux-tools]
url = "https://api.fluxrouter.ai/mcp-tools/"
bearer_token_env_var = "FLUX_API_KEY"

{
  "mcpServers": {
    "flux-tools": {
      "url": "https://api.fluxrouter.ai/mcp-tools/",
      "headers": {
        "Authorization": "Bearer sk-YOUR-FLUX-KEY"
      }
    }
  }
}

mcp_servers:
  flux-tools:
    url: "https://api.fluxrouter.ai/mcp-tools/"
    headers:
      Authorization: "Bearer sk-YOUR-FLUX-KEY"

{
  "mcpServers": {
    "flux-tools": {
      "type": "streamableHttp",
      "url": "https://api.fluxrouter.ai/mcp-tools/",
      "headers": {
        "Authorization": "Bearer sk-YOUR-FLUX-KEY"
      }
    }
  }
}

curl https://api.fluxrouter.ai/v1/search \
  -H "Authorization: Bearer sk-YOUR-FLUX-KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "What changed in the latest Node.js LTS release?" }'

import requests

resp = requests.post(
    "https://api.fluxrouter.ai/v1/search",
    headers={"Authorization": "Bearer sk-YOUR-FLUX-KEY"},
    json={"query": "What changed in the latest Node.js LTS release?"},
)
resp.raise_for_status()
result = resp.json()

print(result["answer"])
for url in result["citations"]:
    print("-", url)
print("Searches:", result["searches"], "Cost (USD):", result["cost_usd"])

const resp = await fetch('https://api.fluxrouter.ai/v1/search', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk-YOUR-FLUX-KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'What changed in the latest Node.js LTS release?',
  }),
});
if (!resp.ok) throw new Error(await resp.text());

const result = await resp.json();
console.log(result.answer);
for (const url of result.citations) console.log('-', url);
console.log('Searches:', result.searches, 'Cost (USD):', result.cost_usd);

The response#

{
  "answer": "The latest LTS release ...",
  "citations": ["https://nodejs.org/en/blog/release/..."],
  "searches": 2,
  "cost_microcents": 12345,
  "cost_usd": "0.012345"
}

The numbers in the example are made up; your call returns its own. The response may carry other fields; ignore any you do not use. The full contract, with every error, is in the search reference.

Search does not stream. It either answers within 30 seconds or fails with a 502, and a failed search is not billed. A query can be up to 2,000 characters.

Search inside a chat request#

On the four Flux tier models, a chat request is sent to a model that can search when either of these is true:

• It carries a web search tool, such as "tools": [{ "type": "web_search" }].
• The last message clearly asks for a search, such as "search the web for the current Node.js LTS version". Asking a question that happens to be about recent events is not enough; say that you want a search.

curl https://api.fluxrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer $FLUX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "flux-auto",
    "tools": [{ "type": "web_search" }],
    "messages": [
      { "role": "user", "content": "What is the current Node.js LTS version?" }
    ]
  }'

The search cost is added to that request's bill, next to the tokens. A pinned model is served exactly as you asked, so this routing only happens on the tier models.

What it costs#

Search is billed per search, plus the model tokens that write the answer: priced per call. One question can take more than one search, and searches in the response says how many ran. cost_usd is the settled amount, and it lands on the same bill as your other usage. See How billing works.

Free keys#

Search is a paid ability.

• On the Free plan, POST /v1/search answers 402 premium_locked and nothing is charged.
• The web_search tool answers premium_locked with an upgrade link, then drops out of your agent's tool list.
• In chat, the search tool is removed from a Free key's request, so the model answers without searching.

Upgrade in Billing. See Plans.

Limits#

Search shares one per-account rate limit with transcription and speech: 60 requests a minute across all three. Over it, calls answer 429; wait and retry. See Rate limits and retries.

If something goes wrong#

Every search error, with its fix, is on Web search problems. To turn search results into a sourced summary, follow Research with sources.