Skip to main content
POST
Fetch URLs as LLM-ready content

Headers

x-api-key
string
required

Body

application/json
api_key
string | null

API key to access the service. Either this or the x-api-key header must be supplied on the HTTP surface; the header takes precedence and is the documented path. On gRPC this field is the only carrier.

Each URL that comes back with the OK status is billed. A URL that comes back with an error is not. The call is refused up front unless the balance covers the whole batch.

formats
string[]

Representations to return, as documented format names.

Omitted, or sent empty, means \["markdown"\] -- a repeated field carries no presence, so the two are the same request and neither means "no formats".

Documented names:

"markdown" -- the main content as Markdown, boilerplate removed.

An unrecognized name is rejected.

tier
string | null

The service tier, which selects the price. Send "pro". Unset resolves to "pro".

An unrecognized value is rejected rather than defaulted, because the value selects a price. The name is matched exactly.

timeout_ms
integer<int32> | null

Wall-clock budget for one URL, in milliseconds.

Applies to each URL, not to the batch. A URL that exceeds the budget gets error.code = "timeout"; the others in the same request are unaffected.

Unset means 75000, which is also the maximum; a larger value is served as 75000, and a value below 1000 is served as 1000.

Required range: x >= 0
urls
string[]

The URLs to fetch. At least one, at most 20.

An empty list, more than 20 entries, a duplicate entry, a blank or padded entry, or an entry over 2048 bytes is rejected before any billing -- duplicates because FetchResult.requested_url is the correlation key and a repeated key is ambiguous.

Everything else is reported inside a 200 as that URL's error result: a value that is not an absolute http or https URL, a host that does not resolve or that this service will not fetch, an origin that refuses, and a document whose media type this service does not serve.

Response

One result per requested URL. A failure to fetch a page is still a 200, with that result's status = "error".

One result per requested URL.

request_id
string
default:""

Identifies this request. Quote it when reporting a problem with the response. Also returned as the x-request-id response header, with the same value.

results
object[]

One entry per entry in FetchRequest.urls, successful or not, in the order the URLs were requested.

Correlate on FetchResult.requested_url rather than on position.