Overview

Use Fetch to retrieve any URL through Browserbase’s infrastructure when you don’t need an interactive browser session. You can also ask Browserbase to return the response as markdown or structured JSON for downstream agents and pipelines. Browserbase routes requests with a real browser User-Agent by default. You can also 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.

Getting started

Create a Fetch request with a URL and optional configuration:

Node.js
Python
cURL

Node.js

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

Python

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

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

For pages behind a login, see Authenticated Fetch.

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 \| object`	`false`	Route the request through Browserbase’s proxy network. See Proxies.
`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`.
`contextId`	`string`	none	ID of a saved login session (called a context) whose cookies are sent with the request. See Authenticated Fetch.

Output formats

Fetch returns the source response as raw by default. Set format: "markdown" for readable markdown, or set format: "json" with a schema for structured data. Browserbase bills markdown and JSON as Fetch Extract separately from raw Fetch. See the pricing table.

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

Node.js

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

Python

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

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. A language model extracts the result from the fetched page content.

Node.js
Python
cURL

Node.js

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

Python

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

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.

Proxies

Route requests through Browserbase’s proxy network or target a specific location.

Authenticated Fetch

Fetch pages that require a login with saved browser session state.

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

Node.js

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

Python

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 need page content, the page doesn’t require interaction, and 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 the full guide for examples of which API to use.

Search

Find web pages for your browser workflow.

Welcome

Platform

Use cases

Optimization

Account

Getting started

Request parameters

Output formats

Markdown output

Structured JSON output

Proxies

Authenticated Fetch

Response

Response fields

Error handling

Limits

API reference

Fetch a page

When to use Fetch

Need more help deciding which API?

Search

​Getting started

​Request parameters

​Output formats

​Markdown output

​Structured JSON output

Proxies

Authenticated Fetch

​Response

​Response fields

​Error handling

​Limits

​API reference

Fetch a page

​When to use Fetch

Need more help deciding which API?

Search

Getting started

Request parameters

Output formats

Markdown output

Structured JSON output

Response

Response fields

Error handling

Limits

API reference

When to use Fetch