--- title: "Start Browser Session (async)" method: POST path: "/v1/sessions/async" tags: ["Browser Sessions"] --- # Start Browser Session (async) `POST /v1/sessions/async` ## Request - Base URL: `https://api.anchorbrowser.io` - URL: `https://api.anchorbrowser.io/v1/sessions/async` - Auth: API key in header `anchor-api-key` Non-blocking variant of `POST /v1/sessions`. Returns a `request_id` immediately and provisions the underlying browser pod in the background. Poll `GET /v1/sessions/async/{request_id}/status` until `status` becomes `ready` to obtain the resolved `session_id`, `cdp_url` and `live_view_url`. ## Request body - SessionCreateRequestSchema - `session` SessionConfig: Session-related configurations. - `initial_url` string, uri: The URL to navigate to when the browser session starts. If not provided, the browser will load an empty page. - `tags` string[]: Custom labels to categorize and identify browser sessions. Useful for filtering, organizing, and tracking sessions across your workflows. - `recording` object: Configuration for session recording. - `active` boolean: Enable or disable video recording of the browser session. Defaults to `true`. - `proxy` union: Proxy Documentation available at [Proxy Documentation](/advanced/proxy) - object - `active` boolean, required - `type` 'anchor_proxy': Create a session with a proxy to access websites as if you're browsing from a computer in that country. - `country_code` 'af' | 'al' | 'dz' | 'ad' | 'ao' | 'as' | 'ag' | 'ar' | 'am' | 'aw' | 'au' | 'at' | 'az' | 'bs' | 'bh' | 'bb' | 'by' | 'be' | 'bz' | 'bj' | 'bm' | 'bo' | 'ba' | 'br' | 'bg' | 'bf' | 'cm' | 'ca' | 'cv' | 'td' | 'cl' | 'co' | 'cg' | 'cr' | 'ci' | 'hr' | 'cu' | 'cy' | 'cz' | 'dk' | 'dm' | 'do' | 'ec' | 'eg' | 'sv' | 'ee' | 'et' | 'fo' | 'fi' | 'fr' | 'gf' | 'pf' | 'ga' | 'gm' | 'ge' | 'de' | 'gh' | 'gi' | 'gr' | 'gd' | 'gp' | 'gt' | 'gg' | 'gn' | 'gw' | 'gy' | 'ht' | 'hn' | 'hu' | 'is' | 'in' | 'ir' | 'iq' | 'ie' | 'il' | 'it' | 'jm' | 'jp' | 'jo' | 'kz' | 'kw' | 'kg' | 'lv' | 'lb' | 'ly' | 'li' | 'lt' | 'lu' | 'mk' | 'ml' | 'mt' | 'mq' | 'mr' | 'mx' | 'md' | 'mc' | 'me' | 'ma' | 'nl' | 'nz' | 'ni' | 'ng' | 'no' | 'pk' | 'pa' | 'py' | 'pe' | 'ph' | 'pl' | 'pt' | 'pr' | 'qa' | 'ro' | 'lc' | 'sm' | 'sa' | 'sn' | 'rs' | 'sc' | 'sl' | 'sk' | 'si' | 'so' | 'za' | 'kr' | 'es' | 'sr' | 'se' | 'ch' | 'sy' | 'st' | 'tw' | 'tj' | 'tg' | 'tt' | 'tn' | 'tr' | 'tc' | 'ua' | 'ae' | 'us' | 'uy' | 'uz' | 've' | 'ye' - `region` string: Region code for more specific geographic targeting. The city parameter can only be used when region is also provided. - `city` string: City name for precise geographic targeting. Supported for anchor_proxy only. Can only be used when region is also provided. - object - `type` 'custom', required - `server` string, required: Proxy address in **PROTOCOL://HOST:PORT** format (e.g., https://proxy.example.com:443). See [Bring Your Own Proxy](/advanced/bring-your-own-proxy). - `username` string, required: Proxy username - `password` string, required: Proxy password - `active` boolean, required - `timeout` object: Timeout configurations for the browser session. - `max_duration` integer: Maximum time (in minutes) the session can run before automatically terminating. Defaults to `20`. Set to `-1` to disable this limit. - `idle_timeout` integer: Time (in minutes) the session waits for new connections after all others are closed before stopping. Defaults to `5`. Set to `-1` to disable this limit. - `live_view` object: Configuration for live viewing the browser session. - `read_only` boolean: Enable or disable read-only mode for live viewing. Defaults to `false`. - `one_time_url` boolean: Generate a single-use live view URL. After the first viewer connects, the link becomes invalid. Requires a headful browser. Defaults to `false`. - `x402` boolean: Allow this browser session to automatically pay x402-protected resources using Amazon Bedrock AgentCore Payments. - `domain_allowlist` string[]: Domains this session may navigate to. `example.com` allows that domain and its subdomains. Document navigations to every other http or https site, including redirects, are blocked. Omit the field to allow the public web. The same field may be set on an API key, application, or task default, or in the project's enforced session configuration. Not available when session.hardware is mac. - `browser` BrowserConfig: Browser-specific configurations. - `profile` object: Options for managing and persisting browser session profiles. - `name` string: The name of the profile to be used during the browser session. - `persist` boolean: Indicates whether the browser session profile data should be saved when the browser session ends. Defaults to `false`. - `adblock` object: Configuration for ad-blocking. - `active` boolean: Enable or disable ad-blocking. Defaults to `true`. - `popup_blocker` object: Configuration for popup blocking. - `active` boolean: Blocks popups, including ads and CAPTCHA consent banners. Requires adblock to be active. Defaults to `true`. - `captcha_solver` object: Configuration for captcha-solving. - `active` boolean: Enable or disable captcha-solving. Requires proxy to be active. Defaults to `false`. - `headless` object: Configuration for headless mode. - `active` boolean: Whether browser should be headless or headful. Defaults to `false`. - `viewport` object: Configuration for the browser's viewport size. - `width` integer: Width of the viewport in pixels. Defaults to `1440`. - `height` integer: Height of the viewport in pixels. Defaults to `900`. - `fullscreen` object: Configuration for fullscreen mode. - `active` boolean: Enable or disable fullscreen mode. When enabled, the browser will start in fullscreen mode. Defaults to `false`. - `pdf_viewer` object: Configuration for PDF viewer mode. - `active` boolean: Enable or disable PDF viewer mode. When disabled, the browser will download PDFs instead of viewing them. Defaults to `true`. - `p2p_download` object: Configuration for peer-to-peer download capture functionality. - `active` boolean: Enable or disable P2P downloads. When enabled, the browser will capture downloads for direct data extraction, instead of uploading them on Anchor's storage. Defaults to `false`. - `extensions` string[]: Array of extension IDs to load in the browser session. Extensions must be previously uploaded using the Extensions API. - `volume` object: Mount a persistent volume into the session. Files the browser downloads are written to the volume's `downloads/` folder and remain available after the session ends. Create volumes with the Volumes API. - `id` string, uuid, required: ID of a volume owned by your team (see `POST /v1/volumes`). The volume must be in the `ready` state. - `read_only` boolean: Mount the volume read-only. Downloads then stay local to the session instead of being written to the volume. Defaults to `false`. - `disable_web_security` object: Configuration for disabling web security features. - `active` boolean: Whether to disable web security features (CORS, same-origin policy, etc.). Allows accessing iframes and resources from different origins. Defaults to `false`. - `extra_stealth` object: Enables our dedicated patched Chromium build, designed to avoid bot detection and blocking. Works with Anchor Proxy enabled only. - `active` boolean: Enable or disable extra stealth mode. - `force_popups_as_tabs` object: Configuration for forcing popups to open as tabs instead of popup windows. - `active` boolean: Enable or disable forcing popups as tabs. Defaults to `false`. - `web_bot_auth` object: Configuration for Cloudflare Web Bot Auth HTTP message signing. Enables authentication with websites that require Cloudflare's web bot authentication. - `active` boolean: Enable or disable web bot auth. Defaults to `false`. - `disable_dialogs` object: Suppresses native browser dialogs (window.alert, window.confirm, window.prompt). Useful for automated workflows where dialogs would block execution. - `active` boolean: Enable or disable suppression of native browser dialogs. Defaults to `false`. - `tracing` object: Console and network tracing. Network logs keep query parameter names but omit values, cookies, and credential headers. - `active` boolean: Enable or disable tracing. Defaults to `true`. - `snapshots` boolean: Store document HTML for the DOM tab. HTML is saved as-is and may include tokens or PII. Defaults to `false`. - `sources` boolean: Accepted for backward compatibility and ignored. - `sensitive_data_mask` object: Automatically detects and masks sensitive data (passwords, emails, phone numbers, credit card fields, tokens) in web pages. Supports custom CSS selectors globally or per site, and custom regex patterns. - `active` boolean: Enable or disable sensitive data masking. Defaults to `false`. - `custom_selectors` string[]: Additional CSS selectors to mask globally across all sites. Matched elements will be blurred. - `site_selectors` object: Per-site CSS selectors. Keys are hostnames (supports wildcard prefix like `*.bank.com`), values are arrays of CSS selectors. Matched elements will be blurred. - `custom_patterns` object[]: Custom regex patterns to detect and mask additional sensitive data types. - `regex` string: Regular expression pattern to match sensitive data. - `mask` string: Replacement string for matched text. Defaults to `****`. - `integrations` Integration[]: Array of integrations to load in the browser session. Integrations must be previously created using the Integrations API. - `id` string, uuid, required: Unique integration ID - `type` '1PASSWORD', required: Integration type - `configuration` union, required - OnePasswordAllSecretsConfig - `load_mode` 'all', required: Load all secrets from 1Password - OnePasswordSpecificSecretsConfig - `load_mode` 'specific', required: Load specific secrets from 1Password - `secrets` string[], required: Array of secret references to load - `identities` object[]: Activates an authenticated session. - `id` string: The identity ID to use for the browser session. - `identity_skip_validation` boolean: When `true` (default), skip profile validation for active identities and reuse the saved browser profile. Set to `false` to validate the profile and re-authenticate if it is no longer signed in. Pending identities still authenticate on first use. - `identity_async_auth` boolean: Run identity authentication in the background and return the session immediately. ## Response `200` Async session creation accepted; poll the status endpoint to resolve. - AsyncSessionCreateResponseSchema - `data` object - `request_id` string, uuid, required: Identifier of the async request. Use it to poll `GET /v1/sessions/async/{request_id}/status` for the resolved `session_id`, `cdp_url` and `live_view_url` once the pod comes up. - `status` 'pending', required: Always `pending` immediately after creation. - `session_id` unknown, required ## Other responses - `400`: Invalid request parameters or configuration. - `402`: Payment Required - Insufficient credits. - `403`: Project cost limit reached. - `429`: API key would exceed batch browser limit. ## Changes - **2026-11-06** `9d755f22df0e`: 1 info - added the new optional request property `session/domain_allowlist` - **2026-10-16** `b3bfdb98c79e`: 1 info - endpoint added [Operation history](https://skmtc.dev/anchorbrowser/apis/anchorbrowser-api/changes/v1/sessions/async/post.md) --- [API](https://skmtc.dev/anchorbrowser/apis/anchorbrowser-api.md) - [All operations](https://skmtc.dev/anchorbrowser/apis/anchorbrowser-api/llms.txt) - [OpenAPI document](https://skmtc.dev/anchorbrowser/apis/anchorbrowser-api/revisions/9d755f22df0e?raw)