View on GitHub

​
Installation

npm install @hyperbrowser/sdk

​
Usage

import Hyperbrowser from "@hyperbrowser/sdk";

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

​
Create Session

Creates a new browser session with optional configuration.

Method: client.createSession(params?: CreateSessionParams, options?): Promise<SessionDetail>

Endpoint: POST /api/session

Parameters:

  • CreateSessionParams:
    • useStealth?: boolean - Use stealth mode.
    • useProxy?: boolean - Use proxy.
    • proxyServer?: string - Proxy server URL to route the session through.
    • proxyServerUsername?: string - Username for proxy server authentication.
    • proxyServerPassword?: string - Password for proxy server authentication.
    • proxyCountry?: Country - Desired proxy country.
    • operatingSystems?: OperatingSystem[] - Preferred operating systems for the session. Possible values are:
      • OperatingSystem.WINDOWS
      • OperatingSystem.ANDROID
      • OperatingSystem.MACOS
      • OperatingSystem.LINUX
      • OperatingSystem.IOS
    • device?: ("desktop" | "mobile")[] - Preferred device types. Possible values are:
      • "desktop"
      • "mobile"
    • platform?: Platform[] - Preferred browser platforms. Possible values are:
      • Platform.CHROME
      • Platform.FIREFOX
      • Platform.SAFARI
      • Platform.EDGE
    • locales?: ISO639_1[] - Preferred locales (languages) for the session. Use ISO 639-1 codes.
    • screen?: ScreenConfig - Screen configuration for the session.
      • width: number - Screen width.
      • height: number - Screen height.
    • solveCaptchas?: boolean - Solve captchas.
    • adblock?: boolean - Block ads.
    • trackers?: boolean - Block trackers.
    • annoyances?: boolean - Block annoyances.

Response: SessionDetail

Example:

const session = await client.createSession();
console.log(session.id);

​
Get Session Details

Retrieves details of a specific session.

Method: client.getSession(id, options?): Promise<SessionDetail>

Endpoint: GET /api/session/{id}

Parameters:

  • id: string - Session ID

Response: SessionDetail

Example:

const session = await client.getSession("182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e");
console.log(session.id);

​
List Sessions

Retrieves a list of all sessions with optional filtering.

Method: client.listSessions(params?, options?): Promise<SessionListResponse>

Endpoint: GET /api/sessions

Parameters:

  • SessionListParams:
    • status?: "active" | "closed" | "error" - Filter sessions by status
    • page?: number - Page number for pagination

Response: SessionListResponse

Example:

const response = await client.listSessions({
  status: "active",
  page: 1,
});
console.log(response.sessions);

​
Stop Session

Stops a running session.

Method: client.stopSession(id, options?): Promise<BasicResponse>

Endpoint: PUT /api/session/{id}/stop

Parameters:

  • id: string - Session ID

Response: BasicResponse

Example:

const response = await client.stopSession(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
);
console.log(`Session stopped: ${response.success}`);

​
Start Scrape Job

Starts a scrape job for a given URL.

Method: client.startScrapeJob(params: StartScrapeJobParams): Promise<StartScrapeJobResponse>

Endpoint: POST /api/scrape

Parameters:

  • StartScrapeJobParams:
    • url: string - URL to scrape
    • useProxy?: boolean - Use proxy
    • solveCaptchas?: boolean - Solve captchas

Response: StartScrapeJobResponse

Example:

const response = await client.startScrapeJob({
  url: "https://example.com",
});
console.log(response.jobId);

​
Get Scrape Job

Retrieves details of a specific scrape job.

Method: client.getScrapeJob(id: string): Promise<ScrapeJobResponse>

Endpoint: GET /api/scrape/{id}

Parameters:

  • id: string - Scrape job ID

Response: ScrapeJobResponse

Example:

const response = await client.getScrapeJob(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
);
console.log(response.status);

​
Start Crawl Job

Starts a crawl job for a given URL.

Method: client.startCrawlJob(params: StartCrawlJobParams): Promise<StartCrawlJobResponse>

Endpoint: POST /api/crawl

Parameters:

  • StartCrawlJobParams:
    • url: string - URL to crawl
    • maxPages?: number - Maximum number of pages to crawl
    • followLinks?: boolean - Follow links
    • excludePatterns?: string[] - Exclude patterns
    • includePatterns?: string[] - Include patterns
    • useProxy?: boolean - Use proxy
    • solveCaptchas?: boolean - Solve captchas

Response: StartCrawlJobResponse

Example:

const response = await client.startCrawlJob({
  url: "https://example.com",
});
console.log(response.jobId);

​
Get Crawl Job

Retrieves details of a specific crawl job.

Method: client.getCrawlJob(id: string): Promise<CrawlJobResponse>

Endpoint: GET /api/crawl/{id}

Parameters:

  • id: string - Crawl job ID

Response: CrawlJobResponse

Example:

const response = await client.getCrawlJob(
  "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
);
console.log(response.status);

​
Types

​
Basic Response

interface BasicResponse {
  success: boolean;
}

​
Session

interface Session {
  id: string;
  teamId: string;
  status: SessionStatus;
  startTime?: number;
  endTime?: number;
  createdAt: string;
  updatedAt: string;
  sessionUrl: string;
}

​
SessionDetail

interface SessionDetail extends Session {
  wsEndpoint?: string;
}

​
SessionListParams

interface SessionListParams {
  status?: SessionStatus;
  page?: number;
}

​
SessionListResponse

interface SessionListResponse {
  sessions: Session[];
  totalCount: number;
  page: number;
  perPage: number;
}

​
CreateSessionParams

interface CreateSessionParams {
  useStealth?: boolean;
  useProxy?: boolean;
  proxyServer?: string;
  proxyServerPassword?: string;
  proxyServerUsername?: string;
  proxyCountry?: Country;
  operatingSystems?: OperatingSystem[];
  device?: ("desktop" | "mobile")[];
  platform?: Platform[];
  locales?: ISO639_1[];
  screen?: ScreenConfig;
  solveCaptchas?: boolean;
  adblock?: boolean;
  trackers?: boolean;
  annoyances?: boolean;
}

​
ScreenConfig

interface ScreenConfig {
  maxWidth: number;
  maxHeight: number;
  minWidth: number;
  minHeight: number;
}

​
StartScrapeJobParams

interface StartScrapeJobParams {
  url: string;
}

​
StartScrapeJobResponse

interface StartScrapeJobResponse {
  jobId: string;
}

​
ScrapeJobMetadata

interface ScrapeJobMetadata {
  title: string;
  description: string;
  robots: string;
  ogTitle: string;
  ogDescription: string;
  ogUrl: string;
  ogImage: string;
  ogLocaleAlternate: string[];
  ogSiteName: string;
  sourceURL: string;
}

​
ScrapeJobData

interface ScrapeJobData {
  metadata: ScrapeJobMetadata;
  markdown: string;
}

## ScrapeJobResponse

```typescript
interface ScrapeJobResponse {
  status: ScrapeJobStatus;
  data?: ScrapeJobData;
  error?: string;
}

​
StartCrawlJobParams

interface StartCrawlJobParams {
  url: string;
  maxPages?: number;
  followLinks?: boolean;
  excludePatterns?: string[];
  includePatterns?: string[];
  useProxy?: boolean;
  solveCaptchas?: boolean;
}

​
StartCrawlJobResponse

interface StartCrawlJobResponse {
  jobId: string;
}

​
CrawledPageMetadata

interface CrawledPageMetadata {
  title: string;
  description: string;
  robots: string;
  ogTitle: string;
  ogDescription: string;
  ogUrl: string;
  ogImage: string;
  ogLocaleAlternate: string[];
  ogSiteName: string;
  sourceURL: string;
}

​
CrawledPage

interface CrawledPage {
  url: string;
  metadata: CrawledPageMetadata;
  markdown: string;
}

​
CrawlJobResponse

interface CrawlJobResponse {
  status: CrawlJobStatus;
  data?: CrawledPage[];
  error?: string;
  totalCrawledPages: number;
  totalPageBatches: number;
  currentPageBatch: number;
  batchSize: number;
}

​
SessionStatus

type SessionStatus = "active" | "closed" | "error";

​
Country

type Country = "US" | "GB" | "CA" | // ...other country codes

​
OperatingSystem

type OperatingSystem = "windows" | "android" | "macos" | "linux" | "ios";

​
Platform

type Platform = "chrome" | "firefox" | "safari" | "edge";

​
ISO639_1

type ISO639_1 = "en" | "es" | "fr" | // ...other language codes

​
ScrapeJobStatus

type ScrapeJobStatus = "pending" | "running" | "completed" | "failed";

​
CrawlJobStatus

type CrawlJobStatus = "pending" | "running" | "completed" | "failed";
Web ScrapingPython SDK