What is a fetch API, and when should your agent use one?

TL;DR: A fetch API lets your agent read a webpage over HTTP and get back its content, without opening a browser tab, rendering the DOM, or waiting for JavaScript to run. If your agent just needs to read a page (not click, log in, or scroll) a fetch call is faster and cheaper than a full browser session. Browserbase's Fetch does this at the infrastructure level: one request, no session to manage, with optional markdown or structured JSON output built in.

Most agent workflows start the same way: the agent needs to look at a page before it decides what to do next. Read a doc, check a changelog, pull a product spec, skim a GitHub README. None of that requires clicking anything. But if the only tool in your stack is a browser, that's what you reach for, and now you're paying for a full session, with its startup latency and its idle-timeout bookkeeping, just to read some HTML.

What is a fetch API?

A fetch API is a way to request a URL and get its response body back over plain HTTP, the same request/response cycle curl or requests.get() uses. This is a different thing from JavaScript's built-in fetch() function, which is a client-side browser API for making HTTP requests from inside a page you've already loaded. What we're describing here is the opposite direction: an API you call from your own backend or agent code to retrieve a page from the outside, with no browser involved at all.

That distinction matters because it's also the tradeoff. A fetch API doesn't execute JavaScript, so it can't render a single-page app, wait for a client-side redirect, or click past a cookie banner. It gives you the response the server sent, fast. Whether that's enough depends entirely on what your agent is trying to do.

When do you need a fetch API instead of a browser?

Reach for a fetch API when the page is static or server-rendered and you just need to read it: documentation, changelogs, product pages, GitHub files, RSS-style feeds, most marketing sites. Reach for a browser session when the content only shows up after JavaScript runs, when the page sits behind a login, or when the task itself is interaction: clicking, filling a form, navigating a multi-step flow.

	Fetch API	Browser session
Executes JavaScript	No	Yes
Typical latency	Low, single HTTP round trip	Higher, full page load and render
Handles logins, clicks, forms	No	Yes
Good for	Reading static or server-rendered pages	JavaScript-heavy pages, logins, multi-step interaction
Session to manage	No	Yes

If you're not sure which side of the table your page falls on, try Fetch first. It fails fast, and you can fall back to a browser session from there.

This is the same logic behind Browserbase's own API lineup: Search finds where to look, Fetch reads what's there, and a browser session steps in only when the page demands real interaction. Most agent loops should spend as little time as possible in the most expensive tool.

How do you use Browserbase's Fetch API?

Browserbase's Fetch API retrieves a URL through Browserbase's infrastructure and hands back the content, headers, and status code, with no browser session created. It's one endpoint: POST /v1/fetch.

Make your first request

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

The response is a plain envelope: status code, headers, content type, and the content itself.

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

Get clean output for an LLM instead of raw HTML

Raw HTML is not what most agents want to reason over. Set format to convert the response before it comes back, so your agent gets markdown or a structured object instead of a DOM to parse.

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

console.log(response.content);

Or ask for structured JSON matching a schema you define:

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

format: "raw" (the default) is the cheapest option since Browserbase just hands back what it received. markdown and json run a conversion step, so they're priced separately, see the pricing table for current rates.

Handle pages that block plain requests

Some sites reject requests that don't look like they came from a real browser session. If you get a 403 or an empty response, route the request through Browserbase's proxy network:

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

Proxies add latency, so leave them off unless the target actually requires them.

What are the limits, and what happens when you hit them?

Fetch trades interactivity for speed, and that tradeoff shows up as four hard limits.

5 MB content limit. A response over that returns a 502 with a message telling you to fall back to a browser session.
60-second timeout. A page that takes longer to respond returns a 504.
No JavaScript execution. If the content you need only appears after a script runs, Fetch won't see it, use a browser session instead.
No PDF conversion. Fetch can retrieve a PDF's raw bytes but can't turn it into markdown or JSON.

These aren't edge cases to code around so much as the signal that tells you when to switch tools. Catch the 502 and 504 errors explicitly and fall back to a full browser session when they fire:

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

How do you take this to production?

A fetch call is stateless by design, so there isn't much production hardening to do beyond handling the errors above. The part worth planning for is volume: agents that read a lot of pages will run a lot of fetch calls, and you want that traffic on infrastructure that's already built to run at scale. Browserbase's platform runs 35 million-plus browser sessions a month, and Fetch shares that same infrastructure, so it scales the same way your agent's browser sessions do.

And because Fetch, Search, and browser sessions all sit behind the same API key, you don't need a second vendor for the just-read-the-page step. Start with Fetch, and reach for a browser session in the same codebase the moment a page actually needs one.

FAQ

Is Browserbase's Fetch API the same as JavaScript's fetch() function?

No. JavaScript's built-in fetch() is a client-side function you call from inside a page that's already loaded in a browser. Browserbase's Fetch API is a server-side endpoint you call from your own backend or agent to retrieve a URL from the outside, no browser or page required.

Can a fetch API replace a browser entirely?

No. It replaces the subset of browser use where you're only reading content, not interacting with it. Anything requiring JavaScript rendering, logins, clicks, or scrolling still needs a browser session.

Does Fetch execute JavaScript?

No. Fetch returns the response the server sent, before any client-side script runs. For pages that render their content with JavaScript, use a browser session instead.

What is the difference between Fetch and Fetch with format set to markdown or json?

Plain Fetch, the default raw format, returns the response as-is, which makes it the cheapest option. Setting format to markdown or json runs a conversion step on top, priced separately, so you get output that's easier for an LLM or downstream pipeline to consume directly.

When should I use Fetch instead of Search?

Search finds relevant URLs when your agent doesn't yet know where to look. Fetch reads a URL you already have. A typical agent loop uses Search to find candidates, then Fetch to check each one before deciding whether a full browser session is worth the cost.

Last updated: July 29, 2026.