POST /v1/fetch
The exact contract for Flux page reading: request fields, the Markdown response, caching and every error, in fetch's own error shape.
Read a public web page and get it back as Markdown. For a guided tour, see Read a web page.
| Endpoint | POST https://api.fluxrouter.ai/v1/fetch (there is no /fetch without /v1) |
| Body | JSON |
| Auth | Authorization: Bearer sk-flux... (or x-api-key) on a paid, cleared plan |
| Streaming | No |
| Status | Live |
Request fields
| Field | Type | Required | Default | Notes |
|---|---|---|---|---|
url | string | Yes | none | The page to read. A public http or https URL. |
render | boolean | No | false | true renders the page's JavaScript in a browser first. For pages that build themselves in the browser. Priced separately from a plain read. |
curl https://api.fluxrouter.ai/v1/fetch \
-H "Authorization: Bearer $FLUX_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://example.com", "render": false }'
Response
200 with:
{
"markdown": "# Example Domain\n\nThis domain is for use in illustrative examples...",
"format": "markdown",
"url": "https://example.com"
}
| Field | Type | Meaning |
|---|---|---|
markdown | string | The page content as Markdown. |
format | string | Always markdown today. |
url | string | The URL that was read. |
Caching and billing
- A read of the same URL within 6 hours is served from the cache and not billed.
- Otherwise each read is billed once: priced per call. A rendered read is priced separately.
- Blocked URLs and failed reads are not billed.
- A read that takes longer than 25 seconds fails.
- Page reads do not count against the shared per-minute limit for audio and search.
Errors
Fetch has its own error shape: error is a string, sometimes with a message next to it. It is not the {"error": {...}} object the other abilities use.
{ "error": "social_blocked", "message": "social-media mass-scrape is not supported" }
| Status | error | Meaning | Fix |
|---|---|---|---|
400 | body must be JSON | The body did not parse. | Send a JSON body. |
400 | url required | url is missing or empty. | Send a non-empty url. |
400 | blocked target: ... | The URL points at a private, loopback, link-local or cloud metadata address. | Use a public URL. |
400 | social_blocked | The URL is on a major social network. | These sites cannot be read. |
401 | unauthorized | The key is missing, wrong, revoked or expired. | Check the key on your keys page. |
402 | upgrade_required | Page reading 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 read. Not charged. | Add credit, or raise the cap. See Spend caps. |
404 | not found | Page reading is not switched on for this account. | Contact support. |
502 | provider failed: ... | The site failed, returned an error or took too long. Not charged. | Retry, or check the URL loads in a browser. |
503 | capability_unavailable | Rendering is unavailable for a while. Not charged. | Retry later, or drop render. |
Fixes in more detail are on Read a page problems.
From the tools server
The web_fetch tool on the Flux tools server takes url only (it always does a plain read) and calls this endpoint with your key, so it bills the same. Its result carries markdown, format and url, plus cost_microcents. Errors come back as tool results; see the tools server reference.