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

Headers

x-api-key
string
required

Body

application/json

Fetch request.

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.

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. Silently dropping it would return a body missing the representation the caller asked for, with nothing to signal why.

tier
string | null

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

An unrecognized value is rejected rather than defaulted: the value selects a price, and quietly billing a tier the caller did not name is worse than refusing.

timeout_ms
integer<int32> | null

Wall-clock budget for one URL, in milliseconds.

Applies per URL, not to the batch: URLs are fetched concurrently, so a batch takes roughly as long as its slowest entry rather than the sum. A URL that exceeds the budget gets error.code = "timeout"; the others in the same request are unaffected.

Unset means the service default. Values are clamped to the service maximum.

Required range: x >= 0
urls
string[]

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

Each must be an absolute http or https URL of at most 2048 bytes. An empty list, more than 20 entries, a duplicate entry, or an over-long entry is rejected before any billing: duplicates because FetchResult.requested_url is the correlation key and a repeated key is ambiguous. A URL that parses but cannot be fetched -- a host that does not resolve, an origin that refuses, a document that is not an HTML page -- is reported inside a 200 as that URL's error result, not as a rejection.

Response

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

Fetch response -- one result per requested URL.

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. That is the key a duplicate URL would make ambiguous, which is why the request rejects one.