POST /v1/search
The exact contract for Flux web search: the request field, the response, the limits and every error.
Answer a question from the current web, with the source links. For a guided tour, including search inside a chat request, see Search the web.
| Endpoint | POST https://api.fluxrouter.ai/v1/search (also /search) |
| Body | JSON |
| Auth | Authorization: Bearer sk-flux... (or x-api-key) on a paid, cleared plan |
| Streaming | No |
| Status | Rolling out |
Request
| Field | Type | Required | Notes |
|---|---|---|---|
query | string | Yes | The question. Up to 2,000 characters, and not blank. |
Send query only. A body with model, tools or search_parameters is refused with 400: the search setup is fixed, and billing depends on it.
curl https://api.fluxrouter.ai/v1/search \
-H "Authorization: Bearer $FLUX_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "query": "What is the current Node.js LTS version?" }'
Response
200 with:
| Field | Type | Meaning |
|---|---|---|
answer | string | The written answer. |
citations | string[] | The URLs the answer drew on. Can be empty. |
searches | integer | How many searches ran. One question can take more than one. |
cost_microcents | integer | What the call cost, in millionths of a US dollar. |
cost_usd | string | The same amount in US dollars, as a decimal string. |
The response may carry other fields. Ignore any you do not use.
Limits
- A search answers within 30 seconds or fails with a
502. A failed search is not billed. - Search shares a per-account limit of 60 requests a minute with transcription and speech.
Errors
Errors use the ability shape: {"error": {"message": "...", "type": "...", "code": "...", "param": "..."}}. code and param appear when they apply.
| Status | code | Meaning | Fix |
|---|---|---|---|
400 | none (param is query) | query missing, blank or too long | Send a shorter, non-empty query. |
400 | none | The body was not JSON, not an object, or carried a field search does not take | Send {"query": "..."} only. |
401 | none | The key is missing, wrong, revoked or expired | Check the key on your keys page. |
402 | premium_locked | Search needs a paid, cleared plan. Not charged. | Upgrade in Billing. |
402 | credit_unresolved | Your credit balance could not be checked. Not charged. | Retry shortly. |
402 | other | Your balance or a spend cap stopped the call. Not charged. | Add credit, or raise the cap. See Spend caps. |
404 | none | Search is not switched on for this account. | Contact support. |
429 | rate_limit_error | Over the shared per-minute limit | Wait, then retry. |
502 | capability_unavailable | Search is not available right now | Retry shortly. |
502 | upstream_error, upstream_incomplete, upstream_empty | The search failed, did not finish or found no answer. Not charged. | Retry, or reword the query. |
502 | usage_unavailable, settlement_unavailable | The search ran but could not be priced or settled. Not charged. | Retry shortly. |
Fixes in more detail are on Web search problems.
From the tools server
The web_search tool on the Flux tools server takes query and calls this endpoint with your key, so it bills the same. Its result carries the same fields, and errors come back as tool results; see the tools server reference.