Request parameters

Every parameter of GET /fetch: url, formats, unwrap, includeMetadata and js_render, plus the response envelope and metadata fields you get back.

Last updated October 27, 2026

Loads url and returns the selected representations. Only GET is accepted: any other method is 405 with Allow: GET.

An omitted formats list is markdown for HTML and PDF, text for other textual types, and raw for images and other binary types.

unwrap=true returns the first requested format this content can produce, as the response body, with that format's content type: text/markdown, text/html, text/plain, a JSON array of links, or the target's own media type for raw. includeMetadata is ignored when unwrap is true. If none of the requested formats can be produced, the answer is 502 format_unavailable.

The url must be http or https, must not include a username or password, and must be at most 8192 characters. Localhost, .local names, private and loopback addresses, and cloud metadata hosts are 400 blocked_url. A redirect to one of those hosts is 502 blocked_url. A fetched body over 8 MiB is 502 body_too_large.

Unknown parameters are refused, so a typo is reported instead of ignored. If the address you want to fetch has its own query string, percent-encode the whole url value, or its & will be read as the start of another parameter.

Query parameters

Parameter	Type	Required	Default	Description
`url`	string, up to 8,192 characters	Yes	—	The address to fetch. Percent-encode it. Give it exactly once.
`formats`	list of `markdown`, `html`, `text`, `links`, `raw`	No	—	What to return, in the order you want it: a comma-separated list (`formats=markdown,links`). Repeating the parameter (`formats=markdown&formats=links`) works too. An empty item is refused.
`unwrap`	boolean	No	`false`	`true` returns the first format as the response body, instead of the JSON envelope. Only `true` or `false`, given at most once.
`includeMetadata`	boolean	No	`false`	`true` adds `data.metadata` (title, description, language, Open Graph tags, JSON-LD, links, phones, emails). Ignored when `unwrap` is true. Only `true` or `false`, given at most once.
`js_render`	boolean	No	`false`	`true` runs the page in a headless browser first, so content that depends on JavaScript is included. It costs $0.005 instead of $0.001 and can take up to 120 seconds. Only `true` or `false`, given at most once.

Formats

Ask for several in one request: they are all built from the same load, and it costs the same as one.

Format	With unwrap=true	What you get
`markdown`	`text/markdown`	The readable content of the page as Markdown: headings, lists, tables, links and code, without scripts and styles.
`html`	`text/html`	The page HTML. With `js_render=true`, the HTML after scripts ran.
`text`	`text/plain`	The readable content as plain text, with no markup at all.
`links`	JSON array	Every link on the page as an absolute URL.
`raw`	The page's own type	The body exactly as the server sent it. Binary bodies are base64 in the envelope.

Response fields

Without unwrap, the answer is a JSON envelope: { status, message, data }. These are the fields of data.

Field	Type	Description
`data.url`	string	The URL that was requested.
`data.fetch.loadedUrl`	string	The URL after redirects.
`data.fetch.loadedTime`	string	When the page was loaded, in ISO 8601.
`data.fetch.httpStatusCode`	integer	Status returned by the target, including 4xx and 5xx.
`data.fetch.contentLengthBytes`	integer	Size of the body Grabber received, in bytes.
`data.fetch.contentType`	string	Media type of the page, as its server sent it.
`data.fetch.encoding`	`utf8` or `base64`	`utf8` for text, `base64` when `raw` holds a binary body.
`data.metadata`	object	Title, description, Open Graph tags and more. Present with `includeMetadata=true`.
`data.markdown`	string	The page as Markdown. Present when `formats` includes `markdown`.
`data.html`	string	The page HTML. Present when `formats` includes `html`.
`data.text`	string	The page as plain text. Present when `formats` includes `text`.
`data.links`	list of strings	Absolute URLs of the links on the page. Present when `formats` includes `links`.
`data.raw`	string	The original body. UTF-8 text when `fetch.encoding` is `utf8`, and base64 when `fetch.encoding` is `base64`.

Metadata fields

With includeMetadata=true, data.metadata has every one of these fields. A field the page does not have is null or an empty list.

Field	Type	Description
`canonicalUrl`	string or null	The canonical URL the page declares.
`title`	string or null	The page title.
`description`	string or null	The meta description.
`author`	string or null	The author meta tag.
`keywords`	string or null	The keywords meta tag.
`languageCode`	string or null	The language of the page, such as `en`.
`openGraph`	list of objects	Every Open Graph tag, as `{ property, content }`.
`jsonLd`	list of objects	Every JSON-LD block on the page, parsed.
`links`	list of strings	Absolute URLs of the links on the page.
`phones`	list of strings	Phone numbers found on the page.
`emails`	list of strings	Email addresses found on the page.

Response examples

{
  "status": 200,
  "message": "OK",
  "data": {
    "url": "https://example.com/start",
    "fetch": {
      "loadedUrl": "https://example.com/final",
      "loadedTime": "2026-10-21T16:36:49.840Z",
      "httpStatusCode": 200,
      "contentLengthBytes": 9,
      "contentType": "text/html",
      "encoding": "utf8"
    },
    "markdown": "ok"
  }
}