# Request parameters

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

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

### JSON envelope

```json
{
  "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"
  }
}
```

### Rendered HTML and metadata

```json
{
  "status": 200,
  "message": "OK",
  "data": {
    "url": "https://example.com/start",
    "fetch": {
      "loadedUrl": "https://example.com/start",
      "loadedTime": "2026-10-21T16:36:49.840Z",
      "httpStatusCode": 200,
      "contentLengthBytes": 48,
      "contentType": "text/html",
      "encoding": "utf8"
    },
    "metadata": {
      "canonicalUrl": null,
      "title": "Hi",
      "description": null,
      "author": null,
      "keywords": null,
      "languageCode": "en",
      "openGraph": [],
      "jsonLd": [],
      "links": [],
      "phones": [],
      "emails": []
    },
    "html": "<p>rendered</p>",
    "markdown": "rendered"
  }
}
```

### Unwrapped link list

```json
[
  "https://example.com/docs"
]
```