Anchor Browser Batch Sessions API

openapi: 3.1.0
info:
  title: AnchorBrowser Agentic capabilities Batch Sessions API
  version: 1.0.0
  description: APIs to manage all browser-related actions and configuration.
servers:
- url: https://api.anchorbrowser.io
  description: API server
tags:
- name: Batch Sessions
paths:
  /v1/batch-sessions:
    get:
      summary: List Batch Sessions
      description: 'Lists all batch session requests for the authenticated team, with optional filtering

        by status and pagination support.

        '
      security:
      - api_key_header: []
      tags:
      - Batch Sessions
      parameters:
      - name: status
        in: query
        required: false
        description: Filter batches by status
        schema:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
          - cancelled
      - name: page
        in: query
        required: false
        description: Page number (1-based)
        schema:
          type: integer
          minimum: 1
          default: 1
      - name: limit
        in: query
        required: false
        description: Number of results per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      - name: created_after
        in: query
        required: false
        description: Filter batches created after this timestamp (ISO 8601)
        schema:
          type: string
          format: date-time
      - name: created_before
        in: query
        required: false
        description: Filter batches created before this timestamp (ISO 8601)
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: Batch list retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BatchSessionListResponseSchema'
        '401':
          description: Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      summary: Create Batch Sessions
      description: 'Creates multiple browser sessions in a single batch operation. This endpoint allows you to

        create up to 5,000 browser sessions simultaneously with the same configuration.


        The batch will be processed asynchronously, and you can monitor progress using the batch status endpoint.

        '
      security:
      - api_key_header: []
      tags:
      - Batch Sessions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchSessionRequestSchema'
            examples:
              small_batch:
                summary: Small batch example
                value:
                  count: 10
                  configuration:
                    browser:
                      headless:
                        active: true
                      viewport:
                        width: 1440
                        height: 900
                    session:
                      timeout:
                        idle_timeout: 10
                        max_duration: 300
                  metadata:
                    project: web-scraping
                    environment: production
              large_batch:
                summary: Large batch example (from test snippet)
                value:
                  count: 2500
                  configuration:
                    browser:
                      headless:
                        active: true
                      viewport:
                        width: 1440
                        height: 900
                      recording:
                        active: true
                    session:
                      timeout:
                        idle_timeout: 10
                        max_duration: 300
                      tags:
                      - batch-test-comprehensive
                  metadata:
                    test: true
                    description: Comprehensive batch test with 3 sessions
      responses:
        '200':
          description: Batch created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BatchSessionResponseSchema'
        '400':
          description: Invalid request parameters or configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_count:
                  summary: Invalid session count
                  value:
                    error:
                      code: 400
                      message: Session count must be between 1 and 1000
                invalid_config:
                  summary: Invalid configuration
                  value:
                    error:
                      code: 400
                      message: CAPTCHA solver requires proxy to be active
        '402':
          description: Payment Required - Insufficient credits for batch creation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too many requests - Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/batch-sessions/{batch_id}:
    get:
      summary: Get Batch Session Status
      description: 'Retrieves detailed status information for a specific batch, including progress,

        individual session details, and any errors that occurred.

        '
      security:
      - api_key_header: []
      tags:
      - Batch Sessions
      parameters:
      - name: batch_id
        in: path
        required: true
        description: The unique identifier of the batch
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Batch status retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BatchSessionStatusResponseSchema'
        '401':
          description: Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Batch not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      summary: Update Batch Session
      description: 'Updates a batch session. Supports cancelling a running or pending batch,

        which terminates all running sessions in the batch.

        '
      security:
      - api_key_header: []
      tags:
      - Batch Sessions
      parameters:
      - name: batch_id
        in: path
        required: true
        description: The unique identifier of the batch
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchSessionUpdateRequestSchema'
            examples:
              cancel_batch:
                summary: Cancel a running batch
                value:
                  status: cancelled
      responses:
        '200':
          description: Batch updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BatchSessionUpdateResponseSchema'
        '401':
          description: Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Batch not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Invalid state transition (batch already cancelled or completed)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      summary: Delete Batch Sessions
      description: 'Deletes all sessions in a batch. Running sessions will be terminated

        and all session data will be removed.

        '
      security:
      - api_key_header: []
      tags:
      - Batch Sessions
      parameters:
      - name: batch_id
        in: path
        required: true
        description: The unique identifier of the batch
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Batch sessions deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BatchSessionDeleteResponseSchema'
        '401':
          description: Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Batch not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v1/batch-sessions/{batch_id}/retry:
    post:
      summary: Retry Failed Batch Sessions
      description: 'Retries failed sessions in a batch by creating new browser pods for each

        failed session. The batch status will be set back to ''processing''.

        '
      security:
      - api_key_header: []
      tags:
      - Batch Sessions
      parameters:
      - name: batch_id
        in: path
        required: true
        description: The unique identifier of the batch
        schema:
          type: string
          format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchSessionRetryRequestSchema'
            examples:
              retry_defaults:
                summary: Retry with default settings
                value:
                  retry_failed_only: true
                  max_retries: 1
              retry_multiple:
                summary: Retry with multiple attempts
                value:
                  retry_failed_only: true
                  max_retries: 3
      responses:
        '200':
          description: Retry initiated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/BatchSessionRetryResponseSchema'
        '400':
          description: No failed sessions to retry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Batch not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    OnePasswordSpecificSecretsConfig:
      type: object
      required:
      - load_mode
      - secrets
      properties:
        load_mode:
          type: string
          enum:
          - specific
          description: Load specific secrets from 1Password
        secrets:
          type: array
          items:
            type: string
          minItems: 1
          description: Array of secret references to load
          example:
          - op://vault/item/field
    ProxyConfig:
      description: 'Proxy Documentation available at [Proxy Documentation](/advanced/proxy)

        '
      type: object
      oneOf:
      - $ref: '#/components/schemas/AnchorProxy'
      - $ref: '#/components/schemas/CustomProxy'
    SessionCreateRequestSchema:
      type: object
      properties:
        session:
          $ref: '#/components/schemas/SessionConfig'
        browser:
          $ref: '#/components/schemas/BrowserConfig'
        integrations:
          type: array
          description: Array of integrations to load in the browser session. Integrations must be previously created using the Integrations API.
          items:
            $ref: '#/components/schemas/Integration'
          example:
          - id: 550e8400-e29b-41d4-a716-446655440000
            type: 1PASSWORD
            configuration:
              load_mode: all
        identities:
          description: 'Activates an authenticated session.

            '
          type: array
          items:
            type: object
            description: Previously configured identity to be used for the authenticated session.
            properties:
              id:
                type: string
                description: The identity ID to use for the browser session.
          example:
          - id: 123e4567-e89b-12d3-a456-426614174000
    AnchorProxy:
      title: Anchor Proxy
      type: object
      properties:
        active:
          type: boolean
        type:
          type: string
          enum:
          - anchor_proxy
          description: Create a session with a proxy to access websites as if you're browsing from a computer in that country.
          title: anchor_proxy
        country_code:
          $ref: '#/components/schemas/AnchorProxyCountryCode'
          description: 'Supported country codes ISO 2 lowercase

            '
        region:
          type: string
          description: 'Region code for more specific geographic targeting.

            The city parameter can only be used when region is also provided.

            '
        city:
          type: string
          description: 'City name for precise geographic targeting. Supported for anchor_proxy only.

            Can only be used when region is also provided.

            '
      required:
      - active
    Integration:
      oneOf:
      - $ref: '#/components/schemas/OnePasswordIntegration'
      discriminator:
        propertyName: type
    BatchSessionListResponseSchema:
      type: object
      properties:
        batches:
          type: array
          items:
            $ref: '#/components/schemas/BatchSessionListItemSchema'
          description: Array of batch session summaries
        pagination:
          type: object
          properties:
            current_page:
              type: integer
              description: Current page number
            total_pages:
              type: integer
              description: Total number of pages
            total_records:
              type: integer
              description: Total number of batch records
            has_next:
              type: boolean
              description: Whether there is a next page
            has_prev:
              type: boolean
              description: Whether there is a previous page
    BatchSessionItemSchema:
      type: object
      properties:
        item_index:
          type: integer
          description: Index of this session within the batch (0-based)
        session_id:
          type: string
          format: uuid
          description: Unique identifier for the browser session (if created successfully)
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
          - cancelled
          description: Current status of this individual session
        cdp_url:
          type: string
          description: CDP websocket connection URL (if session is ready)
        live_view_url:
          type: string
          description: Live view URL for the session (if session is ready)
        error:
          type: string
          description: Error message if session creation failed
        retry_count:
          type: integer
          description: Number of times this session creation has been retried
        started_at:
          type: string
          format: date-time
          description: Timestamp when session creation started
        completed_at:
          type: string
          format: date-time
          description: Timestamp when session creation completed
        metadata:
          type: object
          additionalProperties: true
          description: Session-specific metadata
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: integer
            message:
              type: string
    OnePasswordConfig:
      oneOf:
      - $ref: '#/components/schemas/OnePasswordAllSecretsConfig'
      - $ref: '#/components/schemas/OnePasswordSpecificSecretsConfig'
    AnchorProxyCountryCode:
      type: string
      title: anchor_proxy
      enum:
      - 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
      default: us
    OnePasswordAllSecretsConfig:
      type: object
      required:
      - load_mode
      properties:
        load_mode:
          type: string
          enum:
          - all
          description: Load all secrets from 1Password
    SessionConfig:
      type: object
      description: Session-related configurations.
      properties:
        initial_url:
          type: string
          format: uri
          description: The URL to navigate to when the browser session starts. If not provided, the browser will load an empty page.
        tags:
          type: array
          items:
            type: string
          description: Custom labels to categorize and identify browser sessions. Useful for filtering, organizing, and tracking sessions across your workflows.
          example:
          - production
          - scraping
          - customer-123
        recording:
          type: object
          description: Configuration for session recording.
          properties:
            active:
              type: boolean
              description: Enable or disable video recording of the browser session. Defaults to `true`.
        proxy:
          $ref: '#/components/schemas/ProxyConfig'
        timeout:
          type: object
          description: Timeout configurations for the browser session.
          properties:
            max_duration:
              type: integer
              description: Maximum time (in minutes) the session can run before automatically terminating. Defaults to `20`. Set to `-1` to disable this limit.
            idle_timeout:
              type: integer
              description: 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:
          type: object
          description: Configuration for live viewing the browser session.
          properties:
            read_only:
              type: boolean
              description: Enable or disable read-only mode for live viewing. Defaults to `false`.
            one_time_url:
              type: boolean
              description: Generate a single-use live view URL. After the first viewer connects, the link becomes invalid. Requires a headful browser. Defaults to `false`.
    BatchSessionUpdateResponseSchema:
      type: object
      properties:
        batch_id:
          type: string
          format: uuid
          description: Unique identifier for the batch
        status:
          type: string
          enum:
          - cancelled
          description: New status of the batch
        cancelled_sessions:
          type: integer
          description: Number of running sessions that were terminated
        message:
          type: string
          description: Summary message
    BatchSessionRetryResponseSchema:
      type: object
      properties:
        batch_id:
          type: string
          format: uuid
          description: Unique identifier for the batch
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
          - cancelled
          description: Current status of the batch after retry
        retried_sessions:
          type: integer
          description: Number of sessions that were retried
        message:
          type: string
          description: Summary message
    BatchSessionListItemSchema:
      type: object
      properties:
        batch_id:
          type: string
          format: uuid
          description: Unique identifier for the batch
        status:
          type: string
          enum:
          - pending
          - processing
          - completed
          - failed
          - cancelled
          description: Current status of the batch
        total_requests:
          type: integer
          description: Total number of sessions requested
        completed_requests:
          type: integer
          description: Number of sessions successfully completed
        failed_requests:
          type: integer
          description: Number of sessions that failed
        created_at:
          type: string
          format: date-time
          description: Timestamp when the batch was created
        actual_completion_time:
          type: string
          format: date-time
          description: Timestamp when the batch completed (if completed)
    BatchSessionRetryRequestSchema:
      type: object
      properties:
        retry_failed_only:
          type: boolean
          default: true
          description: Whether to only retry failed sessions
        max_retries:
          type: integer
          minimum: 1
          maximum: 3
          default: 1
          description: Maximum number of attempts per failed session. Each session is retried up to this many times, stopping on first success.
    OnePasswordIntegration:
      type: object
      required:
      - id
      - type
      - configuration
      properties:
        id:
          type: string
          format: uuid
          description: Unique integration ID
          example: 550e8400-e29b-41d4-a716-446655440000
        type:
          type: string
          enum:
          - 1PASSWORD
          description: Integration type
        configuration:
          $ref: '#/components/schemas/OnePasswordConfig'
    CustomProxy:
      title: Custom Proxy
      type: object
      properties:
        type:
          type: string
          enum:
          - custom
        server:
          type: string
          description: Proxy address in **PROTOCOL://HOST:PORT** format (e.g., https://proxy.example.com:443). See [proxy page](/advanced/proxy#custom-proxy).
        username:
          type: string
          description: Proxy username
        password:
          type: string
          description: Proxy password
        active:
          type: boolean
      required:
      - type
      - server
      - username
      - password
      - active
    BrowserConfig:
      type: object
      description: Browser-specific configurations.
      properties:
        profile:
          type: object
          description: Options for managing and persisting browser session profiles.
          properties:
            name:
              type: string
              description: The name of the profile to be used during the browser session.
            persist:
              type: boolean
              description: Indicates whether the browser session profile data should be saved when the browser session ends. Defaults to `false`.
        adblock:
          type: object
          description: Configuration for ad-blocking.
          properties:
            active:
              type: boolean
              description: Enable or disable ad-blocking. Defaults to `true`.
        popup_blocker:
          type: object
          description: Configuration for popup blocking.
          properties:
            active:
              type: boolean
              description: Blocks popups, including ads and CAPTCHA consent banners. Requires adblock to be active. Defaults to `true`.
        captcha_solver:
          type: object
          description: Configuration for captcha-solving.
          properties:
            active:
              type: boolean
              description: Enable or disable captcha-solving. Requires proxy to be active. Defaults to `false`.
        headless:
          type: object
          description: Configuration for headless mode.
          properties:
            active:
              type: boolean
              description: Whether browser should be headless or headful. Defaults to `false`.
        viewport:
          type: object
          description: Configuration for the browser's viewport size.
          properties:
            width:
              type: integer
              description: Width of the viewport in pixels. Defaults to `1440`.
            height:
              type: integer
              description: Height of the viewport in pixels. Defaults to `900`.
        fullscreen:
          type: object
          description: Configuration for fullscreen mode.
          properties:
            active:
              type: boolean
              description: Enable or disable fullscreen mode. When enabled, the browser will start in fullscreen mode. Defaults to `false`.
        pdf_viewer:
          type: object
          description: Configuration for PDF viewer mode.
          properties:
            active:
              type: boolean
              description: Enable or disable PDF viewer mode. When disabled, the browser will download PDFs instead of viewing them. Defaults to `true`.
        p2p_download:
          type: object
          description: Configuration for peer-to-peer download capture functionality.
          properties:
            active:
              type: boolean
              description: 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:
          type: array
          description: Array of extension IDs to load in the browser session. Extensions must be previously uploaded using the Extensions API.
          items:
            type: string
            format: uuid
        disable_web_security:
          type: object
          description: Configuration for disabling web security features.
          properties:
            active:
              type: boolean
              description: Whether to disable web security features (CORS, same-origin policy, etc.). Allows accessing iframes and resources from different origins. Defaults to `false`.
        extra_stealth:
          type: object
          description: Enables our dedicated patched Chromium build, designed to avoid bot detection and blocking. Works with Anchor Proxy enabled only.
          properties:
            active:
              type: boolean
              description: Enable or disable extra stealth mode.
        force_popups_as_tabs:
          type: object
          description: Configuration for forcing popups to open as tabs instead of popup windows.
          properties:
            active:
              type: boolean
              description: Enable or disable forcing popups as tabs. Defaults to `false`.
        web_bot_auth:
          type: object
          description: Configuration for Cloudflare Web Bot Auth HTTP message signing. Enables authentication with websites that require Cloudflare's web bot authentication.
          properties:
            active:
              type: boolean
              description: Enable or disable web bot auth. Defaults to `false`.
        disable_dialogs:
          type: object
          description: Suppresses native browser dialogs (window.alert, window.confirm, window.prompt). Useful for automated workflows where dialogs would block execution.
          properties:
            active:
              type: boolean
              description: Enable or disable suppression of native browser dialogs. Defaults to `false`.
        tracing:
          type: object
          description: Configuration for browser tracing and debugging capabilities.
          properties:
            active:
              type: boolean
              description: Enable or disable tracing. Defaults to `true`.
            snapshots:
              type: boolean
              description: Enable or disable snapshot capture in traces. Defaults to `false`.
            sources:
              type: boolean
              description: Enable or disable source code capture in traces. Defaults to `true`.
        sensitive_data_mask:
          type: object
          description: 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.
          properties:
            active:
              type: boolean
              description: Enable or disable sensitive data masking. Defaults to `false`.
            custom_selectors:
              type: array
              items:
                type: string
              description: Additional CSS selectors to mask globally across all sites. Matched elements will be blurred.
            site_selectors:
    

# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/anchorbrowser/refs/heads/main/openapi/anchorbrowser-batch-sessions-api-openapi.yml