Skip to main content
Fetch loads a URL in a cloud browser and returns the outputs you specify—markdown, HTML, links, screenshots, or structured JSON. It’s the core building block for web scraping with Hyperbrowser.
For the full API schema, see the Fetch API Reference.

​
Quick Start

1

Install the SDK

npm install @hyperbrowser/sdk
2

Fetch a page

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const result = await client.web.fetch({
  url: "https://example.com",
});

console.log(result);

​
Response

The response includes a jobId, overall status, and the outputs under data: 
{
  "jobId": "962372c4-a140-400b-8c26-4ffe21d9fb9c",
  "status": "completed",
  "data": {
    "metadata": {
      "title": "Example Domain",
      "sourceURL": "https://example.com"
    },
    "markdown": "# Example Domain\n\nThis domain is for use in illustrative examples...",
    "links": [
      "https://www.iana.org/domains/example"
    ]
  }
}

​
Outputs

Use outputs.formats to specify what data you want returned.
OutputDescription
markdownPage content converted to Markdown
htmlRaw HTML of the page
linksAll links found on the page
screenshotScreenshot image (configure with options)
jsonStructured data extracted using a JSON Schema
outputs.formats cannot contain duplicate output types (e.g. two screenshots).
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const result = await client.web.fetch({
  url: "https://example.com",
  outputs: {
    formats: ["markdown", "links"],
  },
});

console.log(result.data.markdown);
console.log(result.data.links);

import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const result = await client.web.fetch({
  url: "https://hackernews.com",
  outputs: {
    formats: [
      "markdown",
      {
        type: "screenshot",
        fullPage: true,
        format: "png",
      },
    ],
  },
});

console.log(result.data.screenshot);
Pass a JSON Schema to extract structured data from the page. You can use a raw JSON Schema object, a Zod schema (Node), or a Pydantic model (Python).
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const result = await client.web.fetch({
  url: "https://example.com",
  outputs: {
    formats: [
      {
        type: "json",
        schema: {
          type: "object",
          properties: {
            heading: { type: "string" },
            description: { type: "string" },
          },
          required: ["heading", "description"],
          additionalProperties: false,
        },
      },
    ],
  },
});
Node SDK: You can pass a Zod schema directly to the schema field, and it will be automatically converted to JSON Schema.Python SDK: You can pass a Pydantic model class directly to the schema field, and it will be automatically converted to JSON Schema.
Screenshot cropping rules:
  • fullPage and cropToContent are mutually exclusive.
  • If both cropToContentMaxHeight and cropToContentMinHeight are set, max must be ≥ min.
  • Crop dimensions must be between 100 and 8000 pixels.

​
Output Controls

Control what gets extracted and returned:
FieldTypeDefaultDescription
outputs.sanitizestring"none"Sanitize mode: "none", "basic", or "advanced"
outputs.includeSelectorsstring[][]CSS selectors to include (only matching elements returned)
outputs.excludeSelectorsstring[][]CSS selectors to exclude from output
outputs.storageStateobject—Pre-seed localStorage/sessionStorage before fetching
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

const client = new Hyperbrowser({
  apiKey: process.env.HYPERBROWSER_API_KEY,
});

const result = await client.web.fetch({
  url: "https://example.com",
  outputs: {
    formats: ["html"],
    excludeSelectors: ["nav", "footer", "aside"],
    storageState: {
      localStorage: {
        "example:key": "example:value",
      },
    },
  },
  navigation: {
    waitUntil: "load",
    waitFor: 2000,
  },
  cache: {
    maxAgeSeconds: 3600,
  },
});

​
Browser & Stealth

Configure how the cloud browser runs:
FieldTypeDefaultDescription
stealthstring"auto"Stealth mode: "none", "auto", or "ultra" (recommended: "auto" or "ultra")
browser.profileIdstring—Reuse an existing browser profile
browser.solveCaptchasbooleanfalseEnable CAPTCHA solving
browser.screenobject{ width: 1280, height: 720 }Set viewport dimensions (width, height)
browser.locationobject—Localize via proxy location (country, state, city). If set, proxy is enabled automatically
Control page load behavior and timing:
FieldTypeDefaultDescription
navigation.waitUntilstring"domcontentloaded"Load condition: "load", "domcontentloaded", or "networkidle"
navigation.waitFornumber0Milliseconds to wait after navigation completes before collecting outputs (0–30000)
navigation.timeoutMsnumber30000Max time (ms) to wait for navigation (1–60000)

​
Cache Controls

Control caching behavior for fetch results:
FieldTypeDefaultDescription
cache.maxAgeSecondsnumber—Cache control—cached results older than this are treated as stale. Set to 0 to bypass cache reads
Using cache can improve response times for frequently accessed pages. Set maxAgeSeconds based on how fresh you need the data to be.

​
X402 Support

For agentic workflows, Hyperbrowser supports x402 payment for the Fetch API, enabling agents to programmatically pay for browser sessions at request time using USDC, with payment handled inline via HTTP 402 responses. See the X402 Integration page for details.