Fetch

Turn any webpage into agent context, without launching a browser

What is fetch()?

Sometimes an agent doesn’t need to use a page, it needs to read one. browserbase.fetch() takes a URL and returns its content as markdown, structured JSON, or the raw body.

TypeScript

import { browserbase } from "@browserbasehq/stagehand";

const fetchResult = await browserbase.fetch({
  apiKey: process.env.BROWSERBASE_API_KEY,
  url: "https://example.com",
  format: "markdown",
});

console.log(fetchResult.content);

Python

import os

from stagehand import browserbase

fetch_result = await browserbase.fetch(
    api_key=os.environ["BROWSERBASE_API_KEY"],
    url="https://example.com",
    format="markdown",
)

print(fetch_result.content)

Go

fetchResult, err := stagehand.FetchBrowserbase(ctx, stagehand.BrowserbaseFetchOptions{
	APIKey: os.Getenv("BROWSERBASE_API_KEY"),
	URL:    "https://example.com",
	Format: stagehand.BrowserbaseFetchFormatMarkdown,
})
if err != nil {
	return err
}

content, ok := fetchResult.Content.AsString()
if !ok {
	return errors.New("fetch returned non-string content")
}
fmt.Println(content)

fetch() is a Browserbase cloud feature. The request runs on Browserbase infrastructure and needs a Browserbase API key, so local browsers have no equivalent.

Why use fetch()?

Freshness

Every call retrieves the live page, not a copy from a crawl index, so what the model reads is what the site serves right now.

Speed

No browser boot, no render, and no wait for the DOM to settle. Fast enough to sit inside a latency-sensitive agent loop.

Token-optimized output

Markdown and JSON strip the boilerplate and layout, so the model spends its context on content instead of markup.

Proxy support

Pages that block datacenter traffic are reachable by routing the request through Browserbase’s proxy network.

Setup

fetch() ships with the Stagehand SDK. The only requirement is a Browserbase API key:

export BROWSERBASE_API_KEY="bb_live_..."

TypeScript

import "dotenv/config";
import { browserbase } from "@browserbasehq/stagehand";

const fetchResult = await browserbase.fetch({
  apiKey: process.env.BROWSERBASE_API_KEY,
  url: "https://docs.stagehand.dev/v4/first-steps/introduction",
  format: "markdown",
});

console.log(fetchResult.statusCode, fetchResult.contentType);
console.log(fetchResult.content);

Python

import asyncio
import os

from stagehand import browserbase


async def main() -> None:
    fetch_result = await browserbase.fetch(
        api_key=os.environ["BROWSERBASE_API_KEY"],
        url="https://docs.stagehand.dev/v4/first-steps/introduction",
        format="markdown",
    )
    print(fetch_result.status_code, fetch_result.content_type)
    print(fetch_result.content)


if __name__ == "__main__":
    asyncio.run(main())

Go

package main

import (
	"context"
	"errors"
	"fmt"
	"log"
	"os"

	stagehand "github.com/browserbase/stagehand/packages/sdk-go/v4"
)

func main() {
	if err := run(context.Background()); err != nil {
		log.Fatal(err)
	}
}

func run(ctx context.Context) error {
	apiKey := os.Getenv("BROWSERBASE_API_KEY")
	if apiKey == "" {
		return errors.New("BROWSERBASE_API_KEY is required")
	}

	fetchResult, err := stagehand.FetchBrowserbase(ctx, stagehand.BrowserbaseFetchOptions{
		APIKey: apiKey,
		URL:    "https://docs.stagehand.dev/v4/first-steps/introduction",
		Format: stagehand.BrowserbaseFetchFormatMarkdown,
	})
	if err != nil {
		return err
	}

	content, ok := fetchResult.Content.AsString()
	if !ok {
		return errors.New("fetch returned non-string content")
	}
	fmt.Println(fetchResult.StatusCode, fetchResult.ContentType)
	fmt.Println(content)
	return nil
}

Output formats

format decides what lands in content. Pick the cheapest representation that still answers your question.

markdown

Markdown is the default choice for agent context: headings, links, and text survive, while navigation chrome and layout markup don’t.

TypeScript

const { content } = await browserbase.fetch({
  apiKey: process.env.BROWSERBASE_API_KEY,
  url: "https://example.com/blog/post",
  format: "markdown",
});

Python

result = await browserbase.fetch(
    api_key=os.environ["BROWSERBASE_API_KEY"],
    url="https://example.com/blog/post",
    format="markdown",
)
content = result.content

Go

result, err := stagehand.FetchBrowserbase(ctx, stagehand.BrowserbaseFetchOptions{
	APIKey: os.Getenv("BROWSERBASE_API_KEY"),
	URL:    "https://example.com/blog/post",
	Format: stagehand.BrowserbaseFetchFormatMarkdown,
})
if err != nil {
	return err
}
content, _ := result.Content.AsString()

content is a string.

json

Pass a JSON Schema and get back an object that matches it. The extraction happens server-side, so no model call of your own is involved.

TypeScript

const { content } = await browserbase.fetch({
  apiKey: process.env.BROWSERBASE_API_KEY,
  url: "https://example.com/products/mouse",
  format: "json",
  schema: {
    type: "object",
    properties: {
      name: { type: "string" },
      price: { type: "number" },
      inStock: { type: "boolean" },
    },
    required: ["name", "price"],
  },
});

// content is an object, not a string
console.log(content);

Python

result = await browserbase.fetch(
    api_key=os.environ["BROWSERBASE_API_KEY"],
    url="https://example.com/products/mouse",
    format="json",
    schema={
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "price": {"type": "number"},
            "inStock": {"type": "boolean"},
        },
        "required": ["name", "price"],
    },
)

# result.content is a dict, not a string
print(result.content)

Go

result, err := stagehand.FetchBrowserbase(ctx, stagehand.BrowserbaseFetchOptions{
	APIKey: os.Getenv("BROWSERBASE_API_KEY"),
	URL:    "https://example.com/products/mouse",
	Format: stagehand.BrowserbaseFetchFormatJSON,
	Schema: map[string]any{
		"type": "object",
		"properties": map[string]any{
			"name":    map[string]any{"type": "string"},
			"price":   map[string]any{"type": "number"},
			"inStock": map[string]any{"type": "boolean"},
		},
		"required": []string{"name", "price"},
	},
})
if err != nil {
	return err
}

// Object content, not string content
extracted, ok := result.Content.AsObject()
if !ok {
	return errors.New("fetch returned non-object content")
}
fmt.Println(extracted)

schema and format: "json" go together: passing a schema with any other format, or asking for json without one, fails validation before the request is sent.

raw

The upstream response body, untouched. Use it when you want to parse the page yourself, or when the response isn’t HTML at all: a JSON API, an RSS feed, or a CSV export.

TypeScript

const { content, contentType } = await browserbase.fetch({
  apiKey: process.env.BROWSERBASE_API_KEY,
  url: "https://example.com/feed.xml",
  format: "raw",
});

Python

result = await browserbase.fetch(
    api_key=os.environ["BROWSERBASE_API_KEY"],
    url="https://example.com/feed.xml",
    format="raw",
)

Go

result, err := stagehand.FetchBrowserbase(ctx, stagehand.BrowserbaseFetchOptions{
	APIKey: os.Getenv("BROWSERBASE_API_KEY"),
	URL:    "https://example.com/feed.xml",
	Format: stagehand.BrowserbaseFetchFormatRaw,
})

raw is the default when you omit format, and the cheapest of the three. Check encoding before treating content as text: binary responses come back base64.

Proxies and transport

Some sites refuse datacenter traffic, some answer only after a redirect, and some serve a certificate you’d rather not argue with. Three booleans cover those cases, all off by default.

TypeScript

const result = await browserbase.fetch({
  apiKey: process.env.BROWSERBASE_API_KEY,
  url: "https://example.com/protected",
  format: "markdown",
  proxies: true,          // route through Browserbase's proxy network
  allowRedirects: true,   // follow HTTP redirects
  allowInsecureSsl: true, // skip TLS certificate verification
});

Python

result = await browserbase.fetch(
    api_key=os.environ["BROWSERBASE_API_KEY"],
    url="https://example.com/protected",
    format="markdown",
    proxies=True,             # route through Browserbase's proxy network
    allow_redirects=True,     # follow HTTP redirects
    allow_insecure_ssl=True,  # skip TLS certificate verification
)

Go

proxies := true
allowRedirects := true
allowInsecureSSL := true

result, err := stagehand.FetchBrowserbase(ctx, stagehand.BrowserbaseFetchOptions{
	APIKey:           os.Getenv("BROWSERBASE_API_KEY"),
	URL:              "https://example.com/protected",
	Format:           stagehand.BrowserbaseFetchFormatMarkdown,
	Proxies:          &proxies,          // route through Browserbase's proxy network
	AllowRedirects:   &allowRedirects,   // follow HTTP redirects
	AllowInsecureSSL: &allowInsecureSSL, // skip TLS certificate verification
})

Turn proxies on only for the requests that need it. Proxied fetches cost more and add latency, so a per-domain fallback beats enabling it globally.

Response

Every fetch returns the content alongside the transport metadata, so you can tell a real page from a soft 404 or a bot wall before handing anything to a model.

{
  "id": "fet_01JB8Z3K7Q2M4N",
  "content": "# Example Domain\n\nThis domain is for use in illustrative examples...",
  "contentType": "text/html; charset=utf-8",
  "encoding": "utf-8",
  "headers": { "content-type": "text/html; charset=utf-8" },
  "statusCode": 200
}

Field names follow each language’s conventions: contentType and statusCode in TypeScript, content_type and status_code in Python, and ContentType and StatusCode on the Go structs. In Go, Content is a union: call AsString() for raw and markdown, and AsObject() for json.

API reference

Parameters

apiKey · string · required

Your Browserbase API key. Fetches are billed to the project that owns the key.

url · string · required

The http or https URL to fetch. Validated locally before the request is sent.

format · "raw" | "json" | "markdown"

Which representation to return in content. Defaults to raw.

schema · object

JSON Schema describing the object to extract. Required with format: "json", and rejected with any other format.

proxies · boolean

Route the request through Browserbase’s proxy network. Defaults to false.

allowRedirects · boolean

Follow HTTP redirects. Defaults to false, so a redirect is reported as its 3xx status.

allowInsecureSsl · boolean

Skip TLS certificate verification. Defaults to false.

Returns

id · string

Identifier for this fetch request.

content · string | object

The page content. A string for raw and markdown, an object for json.

contentType · string

MIME type reported by the target.

encoding · string

utf-8 for text, base64 for binary responses.

headers · Record<string, string>

Response headers from the target.

statusCode · number

HTTP status code returned by the target. A fetch that reaches a 404 succeeds as a call and reports 404 here.

When to use a browser instead

fetch() never renders the page. It performs an HTTP request and converts the response, which is exactly why it is fast, and also why it cannot see anything that only exists after JavaScript runs.

Reach for browserbase.launch() and extract() when the content is client-rendered, sits behind a login, or appears only after interaction such as scrolling, clicking a tab, or dismissing a modal. A common pattern is to try fetch() first and fall back to a browser session when the content you need is missing.

Use cases

General agents and chatbots

Retrieve up-to-date information to produce more accurate answers.

Coding agents

Pull the documentation page for a library straight into context as markdown.

Vertical-specific agents

Pull fresh, domain-specific information tailored to a given industry or knowledge vertical.

AI workflows

Regularly collect news, people, company, or other frequently updated information for internal or production workflows.

Limits

Limit	Value
Content size	5 MB
Request timeout	60 seconds
JavaScript execution	Not supported (the page is never rendered)
PDF conversion	PDFs cannot be converted to markdown or json

Next steps

Web Search

Find the URLs worth fetching in the first place.

Browserbase Fetch

Endpoint details, pricing, and the underlying REST API.