Fetch - Browserbase Documentation

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.

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 instead.

Request

Send a request with a URL and optional configuration:

Node.js
Python
cURL

SDK

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);

SDK

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)

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/"}'

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.

Output formats

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

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.

Markdown output

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

Node.js
Python
cURL

SDK

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);

SDK

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)

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"
  }'

Structured JSON output

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

Node.js
Python
cURL

SDK

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);

SDK

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)

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"]
    }
  }'

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

Using proxies

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

Node.js
Python
cURL

SDK

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

SDK

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

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}'

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

Response

A successful response includes the page content along with metadata:

{
  "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.

Content too large (502)

If the response body exceeds 5 MB, you’ll receive a 502 error:

{
  "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:

Node.js
Python

SDK

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();
  }
}

SDK

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()

Gateway Timeout (504)

The target page must respond within 60 seconds. If it takes longer, you’ll receive a timeout error:

{
  "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 instead — browser sessions support long-running page loads and JavaScript-heavy content.

SSL Error (502)

If the target site has a TLS certificate issue (self-signed, expired, etc.), you’ll see an SSL error:

{
  "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:

{
  "url": "https://self-signed.example.com",
  "allowInsecureSsl": true
}

Only enable allowInsecureSsl when you trust the target site. Disabling certificate verification removes a layer of protection against man-in-the-middle attacks.

Limits

Content size: 5 MB maximum. Responses exceeding this limit return a 502 error. See Content Too Large 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.
No PDF conversion: Fetch can’t convert PDF responses to markdown or structured JSON. For PDF content, use a browser session.

API reference

Fetch a page

Full API reference for the POST /v1/fetch endpoint.

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 -> Fetch -> Browsers

Search: Find relevant sources (website, news, docs).
Fetch: Quickly extract content from most pages, and filter out low-value results.
Browsers: Log in to portals with agent identity, navigate complex pages, and extract the hard-to-reach data.

Need more help deciding which API?

Read our full guide breaking down which API to use with examples.

​Request

​Request parameters

​Fetch vs. Fetch Extract

​Output formats

​Markdown output

​Structured JSON output

​Using proxies

​Response

​Response fields

​Error handling

​Limits

​API reference

Fetch a page

​When to use Fetch

Need more help deciding which API?

Request

Request parameters

Fetch vs. Fetch Extract

Output formats

Markdown output

Structured JSON output

Using proxies

Response

Response fields

Error handling

Limits

API reference

When to use Fetch