Skip to main content

​
Overview

Fetch lets you grab the content of any URL through Browserbase’s infrastructure without creating a browser session. It’s ideal for quick page retrievals where you don’t need interactivity — just the content. 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 retrieves the raw HTTP response and does not 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 instead.

​
Request

Send a request with a URL and optional configuration:
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);

​
Request Parameters

ParameterTypeDefaultDescription
urlstringrequiredThe URL to fetch.
allowRedirectsbooleanfalseWhether to follow HTTP redirects.
allowInsecureSslbooleanfalseWhether to bypass TLS certificate verification. Set to true for sites with self-signed or expired certificates.
proxiesbooleanfalseRoute 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:
SDK
const response = await bb.fetchAPI.create({
  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"
}

​
Response Fields

FieldTypeDescription
statusCodenumberThe HTTP status code returned by the target URL.
headersobjectThe HTTP response headers from the target URL.
contentstringThe page content. Text content is returned as a UTF-8 string; binary content is returned as a Base64-encoded string.
contentTypestringThe MIME type of the response (e.g. text/html; charset=utf-8).
encodingstringEither utf-8 for text content or base64 for binary content.

​
Error Handling

Fetch returns structured errors when something goes wrong.
If the response body exceeds 1 MB, you’ll receive a 502 error:
{
  "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:
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();
  }
}
The target page must respond within 10 seconds. If it takes longer, you’ll receive a timeout error:
{
  "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 instead — browser sessions support long-running page loads and JavaScript-heavy content.
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: 1 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: 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.

​
API Reference

Fetch a Page

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