Skip to main content

Documentation Index

Fetch the complete documentation index at: https://hyperbrowser.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

Fetch loads a URL in a cloud browser and returns the outputs you specify—markdown, HTML, links, screenshots, structured JSON, or a branding profile. 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, a prompt, or both
brandingVisual brand profile—colors, fonts, logo, button styles, personality
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);
Extract structured data from the page using prompt, schema, or both:
  • prompt only — Describe what you want in natural language. A schema is auto-generated from the prompt.
  • schema only — Provide a JSON Schema (or Zod/Pydantic equivalent) defining the exact output structure.
  • prompt and schema — The schema defines the output structure, while the prompt provides additional guidance for the extraction.
For best results, provide both a schema and a prompt. The schema defines exactly how you want the data formatted, and the prompt provides context to guide the extraction.
Prompt only (schema auto-generated):
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",
        prompt: "Extract the main heading and a brief description of the page",
      },
    ],
  },
});
Schema only:
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,
        },
      },
    ],
  },
});
Both prompt and schema (recommended):
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",
        prompt: "Extract the main heading and a brief description of the page",
        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.
Extract a structured brand profile for the page: color roles (primary, secondary, accent, background, text), typography, logo + favicon, primary/secondary button styles, personality, and confidence scores. Combines in-browser DOM analysis with an LLM pass over the detected elements.
import { Hyperbrowser } from "@hyperbrowser/sdk";
import { config } from "dotenv";

config();

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

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

  console.log(result.data?.branding?.colors?.primary);
  console.log(result.data?.branding?.images?.logo);
  console.log(result.data?.branding?.personality?.tone);
}

main().catch(console.error);
The response data.branding object includes:
FieldDescription
colorScheme"light" or "dark"
colorsprimary, secondary, accent, background, textPrimary, …
fontsCleaned brand fonts with roles (heading, body, monospace, …)
typographyfontFamilies, fontStacks, fontSizes
spacingbaseUnit, borderRadius
componentsbuttonPrimary, buttonSecondary, input — full CSS style objects
imageslogo, logoHref, logoAlt, favicon, ogImage
personalitytone, energy, targetAudience
designSystemframework (tailwind, bootstrap, …), componentLibrary
confidencebuttons, colors, overall (0–1)
Branding works identically in Crawl — each crawled page gets its own branding profile.

​
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.