---
title: "Create new scrape job"
method: POST
path: "/api/scrape"
---

# Create new scrape job

`POST /api/scrape`

## Request body

- StartScrapeJobParams
  - `url` string, required
  - `sessionOptions` CreateSessionParams
    - `useUltraStealth` boolean
    - `useStealth` boolean
    - `useProxy` boolean
    - `proxyServer` string — Custom proxy server host.
    - `proxyServerPassword` string — Password for authenticating with the custom proxy server.
    - `proxyServerUsername` string — Username for authenticating with the custom proxy server.
    - `proxyCountry` 'AD' | 'AE' | 'AF' | 'AL' | 'AM' | 'AO' | 'AR' | 'AT' | 'AU' | 'AW' | 'AZ' | 'BA' | 'BD' | 'BE' | 'BG' | 'BH' | 'BJ' | 'BO' | 'BR' | 'BS' | 'BT' | 'BY' | 'BZ' | 'CA' | 'CF' | 'CH' | 'CI' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CU' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'EC' | 'EE' | 'EG' | 'ES' | 'ET' | 'EU' | 'FI' | 'FJ' | 'FR' | 'GB' | 'GE' | 'GH' | 'GM' | 'GR' | 'HK' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IN' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JM' | 'JO' | 'JP' | 'KE' | 'KH' | 'KR' | 'KW' | 'KZ' | 'LB' | 'LI' | 'LR' | 'LT' | 'LU' | 'LV' | 'MA' | 'MC' | 'MD' | 'ME' | 'MG' | 'MK' | 'ML' | 'MM' | 'MN' | 'MR' | 'MT' | 'MU' | 'MV' | 'MX' | 'MY' | 'MZ' | 'NG' | 'NL' | 'NO' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PH' | 'PK' | 'PL' | 'PR' | 'PT' | 'PY' | 'QA' | 'RANDOM_COUNTRY' | 'RO' | 'RS' | 'RU' | 'SA' | 'SC' | 'SD' | 'SE' | 'SG' | 'SI' | 'SK' | 'SN' | 'SS' | 'TD' | 'TG' | 'TH' | 'TM' | 'TN' | 'TR' | 'TT' | 'TW' | 'UA' | 'UG' | 'US' | 'UY' | 'UZ' | 'VE' | 'VG' | 'VN' | 'YE' | 'ZA' | 'ZM' | 'ZW' | 'ad' | 'ae' | 'af' | 'al' | 'am' | 'ao' | 'ar' | 'at' | 'au' | 'aw' | 'az' | 'ba' | 'bd' | 'be' | 'bg' | 'bh' | 'bj' | 'bo' | 'br' | 'bs' | 'bt' | 'by' | 'bz' | 'ca' | 'cf' | 'ch' | 'ci' | 'cl' | 'cm' | 'cn' | 'co' | 'cr' | 'cu' | 'cy' | 'cz' | 'de' | 'dj' | 'dk' | 'dm' | 'ec' | 'ee' | 'eg' | 'es' | 'et' | 'eu' | 'fi' | 'fj' | 'fr' | 'gb' | 'ge' | 'gh' | 'gm' | 'gr' | 'hk' | 'hn' | 'hr' | 'ht' | 'hu' | 'id' | 'ie' | 'il' | 'in' | 'iq' | 'ir' | 'is' | 'it' | 'jm' | 'jo' | 'jp' | 'ke' | 'kh' | 'kr' | 'kw' | 'kz' | 'lb' | 'li' | 'lr' | 'lt' | 'lu' | 'lv' | 'ma' | 'mc' | 'md' | 'me' | 'mg' | 'mk' | 'ml' | 'mm' | 'mn' | 'mr' | 'mt' | 'mu' | 'mv' | 'mx' | 'my' | 'mz' | 'ng' | 'nl' | 'no' | 'nz' | 'om' | 'pa' | 'pe' | 'ph' | 'pk' | 'pl' | 'pr' | 'pt' | 'py' | 'qa' | 'ro' | 'rs' | 'ru' | 'sa' | 'sc' | 'sd' | 'se' | 'sg' | 'si' | 'sk' | 'sn' | 'ss' | 'td' | 'tg' | 'th' | 'tm' | 'tn' | 'tr' | 'tt' | 'tw' | 'ua' | 'ug' | 'us' | 'uy' | 'uz' | 've' | 'vg' | 'vn' | 'ye' | 'za' | 'zm' | 'zw'
    - `proxyState` 'AL' | 'AK' | 'AZ' | 'AR' | 'CA' | 'CO' | 'CT' | 'DE' | 'FL' | 'GA' | 'HI' | 'ID' | 'IL' | 'IN' | 'IA' | 'KS' | 'KY' | 'LA' | 'ME' | 'MD' | 'MA' | 'MI' | 'MN' | 'MS' | 'MO' | 'MT' | 'NE' | 'NV' | 'NH' | 'NJ' | 'NM' | 'NY' | 'NC' | 'ND' | 'OH' | 'OK' | 'OR' | 'PA' | 'RI' | 'SC' | 'SD' | 'TN' | 'TX' | 'UT' | 'VT' | 'VA' | 'WA' | 'WV' | 'WI' | 'WY' | 'al' | 'ak' | 'az' | 'ar' | 'ca' | 'co' | 'ct' | 'de' | 'fl' | 'ga' | 'hi' | 'id' | 'il' | 'in' | 'ia' | 'ks' | 'ky' | 'la' | 'me' | 'md' | 'ma' | 'mi' | 'mn' | 'ms' | 'mo' | 'mt' | 'ne' | 'nv' | 'nh' | 'nj' | 'nm' | 'ny' | 'nc' | 'nd' | 'oh' | 'ok' | 'or' | 'pa' | 'ri' | 'sc' | 'sd' | 'tn' | 'tx' | 'ut' | 'vt' | 'va' | 'wa' | 'wv' | 'wi' | 'wy', nullable — Optional state code for proxies to US states. Is mutually exclusive with proxyCity. Takes in two letter state code.
    - `proxyCity` string, nullable — Desired Country. Is mutually exclusive with proxyState. Some cities might not be supported, so before using a new city, we recommend trying it out
    - `region` 'us' | 'us-central' | 'us-west' | 'us-east' | 'asia-south' | 'europe-west'
    - `operatingSystems` OperatingSystem[]
    - `device` Device[]
    - `platform` Platform[]
    - `locales` ISO6391[]
    - `screen` ScreenConfig
      - `width` number
      - `height` number
    - `solveCaptchas` boolean
    - `solverType` 'visual' — Optional CAPTCHA solver mode. Set to visual to use the visual reCAPTCHA solver.
    - `adblock` boolean
    - `trackers` boolean
    - `annoyances` boolean
    - `enableWebRecording` boolean
    - `enableVideoWebRecording` boolean — enableWebRecording must also be true for this to work
    - `profile` CreateSessionProfile
      - `id` string
      - `persistChanges` boolean
      - `persistNetworkCache` boolean — When persisting profile changes, also persist the browser's network cache (HTTP cache).
    - `acceptCookies` boolean
    - `staticIpId` string, uuid
    - `saveDownloads` boolean
    - `extensionIds` string[]
    - `urlBlocklist` string[]
    - `browserArgs` string[]
    - `imageCaptchaParams` object[], nullable
      - `imageSelector` string
      - `inputSelector` string
    - `timeoutMinutes` number
    - `enableWindowManager` boolean
    - `enableWindowManagerTaskbar` boolean
    - `viewOnlyLiveView` boolean
    - `disablePasswordManager` boolean
    - `enableAlwaysOpenPdfExternally` boolean
    - `disablePostQuantumKeyAgreement` boolean
  - `scrapeOptions` ScrapeOptions
    - `formats` string[]
    - `includeTags` string[]
    - `excludeTags` string[]
    - `onlyMainContent` boolean
    - `waitFor` number
    - `timeout` number
    - `waitUntil` 'load' | 'domcontentloaded' | 'networkidle'
    - `screenshotOptions` object — Options for the screenshot. Both `fullPage` and `cropToContent` cannot be true at the same time.
      - `fullPage` boolean
      - `format` 'jpeg' | 'png' | 'webp'
      - `cropToContent` boolean — Automatically adjusts the screenshot height to match the page's actual content. If the page is shorter than the viewport, the screenshot is trimmed to remove any empty space below the content. If the page is taller than the viewport, the screenshot is cropped to the height of the viewport.
      - `cropToContentMaxHeight` number — The maximum height of the screenshot when `cropToContent` is true. Overrides the height set in the `screen` configuration.
      - `cropToContentMinHeight` number — The minimum height of the screenshot when `cropToContent` is true. Overrides the height set in the `screen` configuration.
    - `storageState` object
      - `localStorage` object
      - `sessionStorage` object

## Response `200`

Scrape job created

- StartScrapeJobResponse
  - `jobId` string

## Other responses

- `400` — Invalid request parameters
- `500` — Server error

---

[API](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api.md) · [All operations](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hyperbrowser/hyperbrowser-api/revisions/9d8b355ebbf2/schema)