> ## Documentation Index
> Fetch the complete documentation index at: https://docs.browserbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch

> Lightweight page retrieval as a complement to browser sessions.

Fetch lets you grab the content of any URL through Browserbase's infrastructure as a lightweight complement to browser sessions. Use it for quick page retrievals where you don't need interactivity, or ask Browserbase to turn the response into markdown or structured JSON for downstream agents and pipelines.

Requests are routed through Browserbase with a real browser User-Agent by default, and you can optionally configure custom headers, proxies, redirects, and SSL behavior.

<Note>
  Fetch doesn't execute JavaScript and has a **5 MB content limit**. Fetch also can't convert PDF responses to markdown or structured JSON. For pages that require JavaScript rendering or are larger than 5 MB, use a [browser session](/platform/browser/getting-started/create-browser-session) instead.
</Note>

## Request

Send a request with a URL and optional configuration:

<Tabs>
  <Tab title="Node.js">
    ```typescript SDK theme={null}
    import Browserbase from "@browserbasehq/sdk";

    const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

    const response = await bb.fetchAPI.create({
      url: "https://httpbin.org/",
    });

    console.log(response.statusCode);
    console.log(response.content);
    ```
  </Tab>

  <Tab title="Python">
    ```python SDK theme={null}
    from browserbase import Browserbase
    import os

    bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

    response = bb.fetch_api.create(url="https://httpbin.org/")

    print(response.status_code)
    print(response.content)
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.browserbase.com/v1/fetch \
      -H "Content-Type: application/json" \
      -H "X-BB-API-Key: $BROWSERBASE_API_KEY" \
      -d '{"url": "https://httpbin.org/"}'
    ```
  </Tab>
</Tabs>

### Request parameters

| Parameter          | Type                            | Default      | Description                                                                                                                                                |
| ------------------ | ------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url`              | `string`                        | **required** | The URL to fetch.                                                                                                                                          |
| `allowRedirects`   | `boolean`                       | `false`      | Whether to follow HTTP redirects.                                                                                                                          |
| `allowInsecureSsl` | `boolean`                       | `false`      | Whether to bypass TLS certificate verification. Set to `true` for sites with self-signed or expired certificates.                                          |
| `proxies`          | `boolean`                       | `false`      | Route the request through Browserbase's proxy network.                                                                                                     |
| `format`           | `"raw" \| "markdown" \| "json"` | `"raw"`      | Output format for `content`. Use `raw` for the upstream response body, `markdown` for a markdown version of the page, or `json` for structured extraction. |
| `schema`           | `object`                        | none         | JSON Schema describing the structure you want returned in `content`. Only valid when `format` is `json`.                                                   |

## Fetch vs. Fetch Extract

Fetch without a `format` flag returns the page content directly, which makes it the cheapest option. This is normal Fetch.

When you set `format: "markdown"` or `format: "json"`, Browserbase converts the page before returning it. This is Fetch Extract. That conversion makes Fetch Extract more expensive than normal Fetch, and Browserbase prices it separately in the [pricing table](/account/billing/plans).

## Output formats

Use the same endpoint and SDK methods when you want cleaner output for LLMs or downstream systems.

<Note>
  SDK support for `format: "markdown"` and `format: "json"` is available in the Node SDK starting in `@browserbasehq/sdk` `v2.12.0` and in the Python SDK starting in `browserbase` `v1.11.0`.
</Note>

### Markdown output

`format: "markdown"` returns the fetched page content as markdown in the `content` field.

<Tabs>
  <Tab title="Node.js">
    ```typescript SDK theme={null}
    import Browserbase from "@browserbasehq/sdk";

    const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

    const response = await bb.fetchAPI.create({
      url: "https://www.browserbase.com/",
      format: "markdown",
    });

    console.log(response.content);
    ```
  </Tab>

  <Tab title="Python">
    ```python SDK theme={null}
    from browserbase import Browserbase
    import os

    bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

    response = bb.fetch_api.create(
        url="https://www.browserbase.com/",
        format="markdown",
    )

    print(response.content)
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.browserbase.com/v1/fetch \
      -H "Content-Type: application/json" \
      -H "X-BB-API-Key: $BROWSERBASE_API_KEY" \
      -d '{
        "url": "https://www.browserbase.com/",
        "format": "markdown"
      }'
    ```
  </Tab>
</Tabs>

### Structured JSON output

`format: "json"` requires a `schema`. Browserbase returns the extracted result as structured JSON in the `content` field.

<Tabs>
  <Tab title="Node.js">
    ```typescript SDK theme={null}
    import Browserbase from "@browserbasehq/sdk";

    const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

    const response = await bb.fetchAPI.create({
      url: "https://www.browserbase.com/",
      format: "json",
      schema: {
        type: "object",
        properties: {
          title: { type: "string" },
          summary: { type: "string" },
        },
        required: ["title"],
      },
    });

    console.log(response.content);
    ```
  </Tab>

  <Tab title="Python">
    ```python SDK theme={null}
    from browserbase import Browserbase
    import os

    bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

    response = bb.fetch_api.create(
        url="https://www.browserbase.com/",
        format="json",
        schema={
            "type": "object",
            "properties": {
                "title": {"type": "string"},
                "summary": {"type": "string"},
            },
            "required": ["title"],
        },
    )

    print(response.content)
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.browserbase.com/v1/fetch \
      -H "Content-Type: application/json" \
      -H "X-BB-API-Key: $BROWSERBASE_API_KEY" \
      -d '{
        "url": "https://www.browserbase.com/",
        "format": "json",
        "schema": {
          "type": "object",
          "properties": {
            "title": { "type": "string" },
            "summary": { "type": "string" }
          },
          "required": ["title"]
        }
      }'
    ```
  </Tab>
</Tabs>

<Warning>
  `schema` is only valid when `format` is `json`. If you send a schema with `raw` or `markdown`, the request is rejected.
</Warning>

### Using proxies

If a site is blocking your request or returning a `403` status code, enable Browserbase's proxy network by setting `proxies: true`:

<Tabs>
  <Tab title="Node.js">
    ```typescript SDK theme={null}
    const response = await bb.fetchAPI.create({
      url: "https://httpbin.org/",
      proxies: true,
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python SDK theme={null}
    response = bb.fetch_api.create(
        url="https://httpbin.org/",
        proxies=True,
    )
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.browserbase.com/v1/fetch \
      -H "Content-Type: application/json" \
      -H "X-BB-API-Key: $BROWSERBASE_API_KEY" \
      -d '{"url": "https://httpbin.org/", "proxies": true}'
    ```
  </Tab>
</Tabs>

<Note>
  Enabling proxies may increase response time. If speed is critical and the target site doesn't require a proxy, leave this disabled.
</Note>

## Response

A successful response includes the page content along with metadata:

```json theme={null}
{
  "statusCode": 200,
  "headers": {
    "Content-Type": "text/html; charset=utf-8"
  },
  "content": "<!doctype html>...",
  "contentType": "text/html; charset=utf-8",
  "encoding": "utf-8"
}
```

The response envelope stays the same across all formats. What changes is the value stored in `content`:

* `raw`: the upstream response body
* `markdown`: markdown generated from the fetched page
* `json`: a structured JSON object matching the schema you requested

### Response fields

| Field         | Type               | Description                                                                                                                                                                                                       |
| ------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `statusCode`  | `number`           | The HTTP status code returned by the target URL.                                                                                                                                                                  |
| `headers`     | `object`           | The HTTP response headers from the target URL.                                                                                                                                                                    |
| `content`     | `string \| object` | The page content. Raw and markdown responses return strings. JSON extraction returns a structured object matching your schema. Binary content is returned as a Base64-encoded string when `encoding` is `base64`. |
| `contentType` | `string`           | The MIME type of the response (e.g. `text/html; charset=utf-8`).                                                                                                                                                  |
| `encoding`    | `string`           | Either `utf-8` for text content or `base64` for binary content.                                                                                                                                                   |

## Error handling

Fetch returns structured errors when something goes wrong.

<AccordionGroup>
  <Accordion title="Content too large (502)">
    If the response body exceeds 5 MB, you'll receive a 502 error:

    ```json theme={null}
    {
      "statusCode": 502,
      "error": "Bad Gateway",
      "message": "The response body exceeded the maximum allowed size of 5MB. Use a browser session to handle large responses."
    }
    ```

    To handle this, catch the error and fall back to a browser session:

    <Tabs>
      <Tab title="Node.js">
        ```typescript SDK theme={null}
        import Browserbase from "@browserbasehq/sdk";
        import { chromium } from "playwright-core";

        const bb = new Browserbase({ apiKey: process.env.BROWSERBASE_API_KEY! });

        try {
          const response = await bb.fetchAPI.create({
            url: "https://httpbin.org/",
          });
          console.log(response.content);
        } catch (err: any) {
          if (err?.statusCode === 502) {
            // Fall back to a full browser session for large pages
            const session = await bb.sessions.create();
            const browser = await chromium.connectOverCDP(session.connectUrl);
            const page = browser.contexts()[0].pages()[0];
            await page.goto("https://httpbin.org/");
            const content = await page.content();
            console.log(content);
            await browser.close();
          }
        }
        ```
      </Tab>

      <Tab title="Python">
        ```python SDK theme={null}
        from browserbase import Browserbase
        from playwright.sync_api import sync_playwright
        import os

        bb = Browserbase(api_key=os.environ["BROWSERBASE_API_KEY"])

        try:
            response = bb.fetch_api.create(url="https://httpbin.org/")
            print(response.content)
        except Exception as err:
            if getattr(err, "status_code", None) == 502:
                # Fall back to a full browser session for large pages
                session = bb.sessions.create()
                with sync_playwright() as p:
                    browser = p.chromium.connect_over_cdp(session.connect_url)
                    page = browser.contexts[0].pages[0]
                    page.goto("https://httpbin.org/")
                    print(page.content())
                    browser.close()
        ```
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Gateway Timeout (504)">
    The target page must respond within **60 seconds**. If it takes longer, you'll receive a timeout error:

    ```json theme={null}
    {
      "statusCode": 504,
      "error": "Gateway Timeout",
      "message": "The requested content took more than 60 seconds to fetch. Please try again or use a browser session for complex pages."
    }
    ```

    If you consistently hit this timeout, consider using a [browser session](/platform/browser/getting-started/create-browser-session) instead. Browser sessions support long-running page loads and JavaScript-heavy content.
  </Accordion>

  <Accordion title="SSL Error (502)">
    If the target site has a TLS certificate issue (self-signed, expired, etc.), you'll see an SSL error:

    ```json theme={null}
    {
      "statusCode": 502,
      "error": "SSL Error",
      "message": "TLS certificate verification failed; to bypass certificate verification, set the allowInsecureSsl option in your request"
    }
    ```

    To resolve this, set `allowInsecureSsl` to `true` in your request:

    ```json theme={null}
    {
      "url": "https://self-signed.example.com",
      "allowInsecureSsl": true
    }
    ```

    <Warning>
      Only enable `allowInsecureSsl` when you trust the target site. Disabling certificate verification removes a layer of protection against man-in-the-middle attacks.
    </Warning>
  </Accordion>
</AccordionGroup>

## Limits

* **Content size:** 5 MB maximum. Responses exceeding this limit return a 502 error. See [Content Too Large](#content-too-large-502) for how to detect and fall back to a browser session.
* **Timeout:** 60 seconds. Pages that take longer to respond will return a 504 error.
* **No JavaScript execution:** Fetch never renders the page in a browser. For pages that require JavaScript rendering, use a [browser session](/platform/browser/getting-started/create-browser-session).
* **No PDF conversion:** Fetch can't convert PDF responses to markdown or structured JSON. For PDF content, use a [browser session](/platform/browser/getting-started/create-browser-session).

## API reference

<Card title="Fetch a page" icon="globe" iconType="sharp-solid" href="/reference/api/fetch-a-page">
  Full API reference for the POST /v1/fetch endpoint.
</Card>

## When to use Fetch

Use Fetch when you just need the content, the page doesn’t require interaction, and when performance and cost matter.

Think about [Search](/platform/search/overview) -> [Fetch](/platform/fetch/overview) -> [Browsers](/platform/browser/getting-started/create-browser-session)

* **[Search:](/platform/search/overview)** Find relevant sources (website, news, docs).
* **[Fetch:](/platform/fetch/overview)** Quickly extract content from most pages, and filter out low-value results.
* **[Browsers:](/platform/browser/getting-started/create-browser-session)** Log in to portals with [agent identity](/platform/identity/overview), navigate complex pages, and extract the hard-to-reach data.

<CardGroup cols={1}>
  <Card title="Need more help deciding which API?" icon="book-open" iconType="sharp-solid" href="https://www.browserbase.com/blog/search-vs-fetch-vs-browsers">
    Read our [full guide](https://www.browserbase.com/blog/search-vs-fetch-vs-browsers) breaking down which API to use with examples.
  </Card>
</CardGroup>