> ## 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 — then hand off to a [browser session](/platform/browser/getting-started/create-browser-session) when you do.

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 retrieves the raw HTTP response and doesn't execute JavaScript. It also has a **1 MB content limit**. For pages that require JavaScript rendering or are larger than 1 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.                                                            |

### 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"
}
```

### 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` | The page content. Text content is returned as a UTF-8 string; binary content is returned as a Base64-encoded string. |
| `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 1 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 1MB. 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 **10 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 10 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:** 1 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:** 10 seconds. Pages that take longer to respond will return a 504 error.
* **No JavaScript execution:** Fetch retrieves the raw HTTP response. For pages that require JavaScript rendering, use a [browser session](/platform/browser/getting-started/create-browser-session).

<Note>
  Coming soon: markdown and JSON extraction
</Note>

## 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>