Anchor Browser Browser Sessions API
The Browser Sessions API from Anchor Browser — 10 operation(s) for browser sessions.
OpenAPI Specification
openapi: 3.1.0
info:
title: AnchorBrowser Agentic capabilities Browser 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: Browser Sessions
paths:
/v1/sessions:
get:
summary: List Sessions History Page
description: 'Retrieves a paginated list of sessions for the authenticated team with support for
sorting and advanced filtering. This endpoint mirrors the backend session history-page
filtering behavior.
'
security:
- api_key_header: []
tags:
- Browser Sessions
parameters:
- in: query
name: page
required: false
description: Page number to fetch.
schema:
type: integer
minimum: 1
default: 1
- in: query
name: limit
required: false
description: Number of sessions per page. Supported values are 10, 20, and 50.
schema:
type: integer
enum:
- 10
- 20
- 50
default: 10
- in: query
name: sort_by
required: false
description: 'Sort field. Common values are `created_at`, `session_id`, `used_credits`,
`created_at`, and `api_key_name`.
'
schema:
type: string
default: created_at
- in: query
name: sort_order
required: false
description: Sort direction.
schema:
type: string
enum:
- asc
- desc
default: asc
- in: query
name: search
required: false
description: Comma-separated tag search terms (partial, case-insensitive).
schema:
type: string
- in: query
name: status
required: false
description: Exact session status filter.
schema:
type: string
- in: query
name: tags
required: false
description: Comma-separated tag list. Session must include all provided tags.
schema:
type: string
example: production,scraping
- in: query
name: domains
required: false
description: Comma-separated domain list. Session must include all provided domains.
schema:
type: string
example: example.com,anchorbrowser.io
- in: query
name: created_from
required: false
description: Include sessions created at or after this timestamp (ISO 8601).
schema:
type: string
format: date-time
- in: query
name: created_to
required: false
description: Include sessions created at or before this timestamp (ISO 8601).
schema:
type: string
format: date-time
- in: query
name: batch_id
required: false
description: Filter by batch identifier.
schema:
type: string
- in: query
name: task_initiated
required: false
description: Filter by whether the session was task-initiated.
schema:
type: boolean
- in: query
name: playground
required: false
description: Filter by whether the session is a playground session.
schema:
type: boolean
- in: query
name: proxy
required: false
description: Filter by whether proxy was active for the session.
schema:
type: boolean
- in: query
name: extra_stealth
required: false
description: Filter by whether extra stealth mode was active.
schema:
type: boolean
- in: query
name: profile_name
required: false
description: Case-insensitive partial match on browser profile name.
schema:
type: string
example: Default profile
responses:
'200':
description: Paginated sessions history retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SessionHistoryPageResponse'
examples:
filteredSessionsPage:
summary: Example filtered session page
value:
data:
sessions:
- id: sess_123456
status: completed
tags:
- production
- scraping
headless: false
recording: true
used_credits: 12.5
proxy_bytes: 102400
proxy_type: anchor_proxy
steps: 48
duration: 420
created_at: '2026-03-09T12:34:56.789Z'
user_configuration:
session:
idle_timeout: 300
task_initiated: true
task_executions_count: 2
api_key_name: automation-key
browser_ip: 192.0.2.10
domains:
- example.com
total: 145
page: 1
total_pages: 15
'400':
description: Invalid query parameters (for example unsupported limit or sort options).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
post:
summary: Start Browser Session
description: Allocates a new browser session for the user, with optional configurations for ad-blocking, captcha solving, proxy usage, and idle timeout.
security:
- api_key_header: []
tags:
- Browser Sessions
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/SessionCreateRequestSchema'
responses:
'200':
description: Successfully returned a browser object
content:
application/json:
schema:
$ref: '#/components/schemas/SessionCreateResponseSchema'
'400':
description: Bad Request - Invalid request parameters or configuration.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
captchaSolverRequiresProxy:
summary: CAPTCHA solver requires proxy to be active.
value:
error:
code: 400
message: CAPTCHA solver requires proxy to be active.
'402':
description: Payment Required - Insufficient credits to allocate a new browser
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests — session creation rate limit exceeded.
headers:
RateLimit:
description: 'IETF draft-8 Rate-limit headers.
'
schema:
type: string
example: '"5-in-1min"; r=0; t=58'
RateLimit-Policy:
schema:
type: string
example: '"5-in-1min"; q=5; w=60; pk=:ZGQ0YzBjYzVhZjQ1:'
Retry-After:
description: Seconds until the rate-limit window resets (matches the `t` parameter in `RateLimit` when the limit is exceeded).
schema:
type: integer
example: 58
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
sessionCreationRateLimited:
summary: Session creation rate limit exceeded
value:
error:
code: 429
message: Session creation rate limit exceeded.
/v1/sessions/async:
post:
summary: Start Browser Session (async)
description: '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`.
'
security:
- api_key_header: []
tags:
- Browser Sessions
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/SessionCreateRequestSchema'
responses:
'200':
description: Async session creation accepted; poll the status endpoint to resolve.
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncSessionCreateResponseSchema'
'400':
description: Invalid request parameters or configuration.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'402':
description: Payment Required - Insufficient credits.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'403':
description: Project cost limit reached.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: API key would exceed batch browser limit.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/sessions/async/{request_id}/status:
get:
summary: Async Session Status
description: 'Polling endpoint paired with `POST /v1/sessions/async`. Returns the
current lifecycle `status` of the async request and, once the pod is
up, the embedded `session` object containing `session_id`, `cdp_url`
and `live_view_url`.
'
security:
- api_key_header: []
tags:
- Browser Sessions
parameters:
- name: request_id
in: path
required: true
description: The `request_id` returned from `POST /v1/sessions/async`.
schema:
type: string
format: uuid
responses:
'200':
description: Async session status retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncSessionStatusResponseSchema'
'401':
description: Invalid API Key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Async request not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/sessions/all:
delete:
summary: End All Sessions
description: Terminates all active browser sessions associated with the provided API key.
tags:
- Browser Sessions
security:
- api_key_header: []
responses:
'200':
description: Successfully terminated all active browser sessions.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
/v1/sessions/all/status:
get:
summary: List All Sessions Status
description: Retrieves status information for all browser sessions associated with the API key.
security:
- api_key_header: []
tags:
- Browser Sessions
parameters:
- in: query
name: tags
required: false
description: Comma-separated list of session tags to filter by. Sessions must contain all provided tags.
schema:
type: string
example: production,scraping
- in: query
name: domains
required: false
description: Comma-separated list of domains to filter by. Sessions must contain all provided domains.
schema:
type: string
example: example.com,anchorbrowser.io
- in: query
name: created_from
required: false
description: Include sessions created at or after this timestamp (ISO 8601).
schema:
type: string
format: date-time
- in: query
name: created_to
required: false
description: Include sessions created at or before this timestamp (ISO 8601).
schema:
type: string
format: date-time
- in: query
name: batch_id
required: false
description: Filter sessions by batch identifier.
schema:
type: string
- in: query
name: task_initiated
required: false
description: Filter by whether the session was initiated by a task.
schema:
type: boolean
- in: query
name: playground
required: false
description: Filter by whether the session is a playground session.
schema:
type: boolean
- in: query
name: proxy
required: false
description: Filter by whether proxy was active for the session.
schema:
type: boolean
- in: query
name: extra_stealth
required: false
description: Filter by whether extra stealth mode was active for the session.
schema:
type: boolean
- in: query
name: profile_name
required: false
description: Filter sessions by browser profile name (case-insensitive partial match).
schema:
type: string
example: Default profile
responses:
'200':
description: Successfully retrieved status for all browser sessions
content:
application/json:
schema:
$ref: '#/components/schemas/SessionListResponse'
'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'
/v1/sessions/history:
get:
summary: Get Sessions History
description: Retrieves session usage analytics for the authenticated team.
security:
- api_key_header: []
tags:
- Browser Sessions
parameters:
- in: query
name: from_date
required: false
description: Start date for filtering (ISO 8601 format).
schema:
type: string
format: date-time
- in: query
name: to_date
required: false
description: End date for filtering (ISO 8601 format).
schema:
type: string
format: date-time
- in: query
name: granularity
required: false
description: Time granularity for aggregation.
schema:
type: string
enum:
- hour
- day
- week
- month
default: day
- in: query
name: metrics
required: false
description: Metrics to include in the response.
schema:
oneOf:
- type: string
- type: array
items:
type: string
enum:
- session_count
- proxy_bytes
- ai_steps
- session_hours
- credits_used
- screenshots
- network_bytes_total
default:
- session_count
- in: query
name: page
required: false
description: Page number for pagination.
schema:
type: integer
minimum: 1
default: 1
- in: query
name: limit
required: false
description: Number of records per page.
schema:
type: integer
minimum: 1
maximum: 1000
default: 100
responses:
'200':
description: Session history analytics retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SessionHistoryResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/sessions/{session_id}:
get:
summary: Get Browser Session
description: Retrieves detailed information about a specific browser session.
tags:
- Browser Sessions
parameters:
- in: path
name: session_id
required: true
description: The ID of the session to retrieve.
schema:
type: string
security:
- api_key_header: []
responses:
'200':
description: Session retrieved successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: object
description: The session data.
properties:
session_id:
type: string
description: The unique identifier of the session.
team_id:
type: string
description: The team ID associated with the session.
duration:
type: integer
description: The duration of the session in seconds.
status:
type: string
description: The current status of the session.
credits_used:
type: number
description: The number of credits consumed by the session.
configuration:
type: object
description: The configuration settings for the session.
playground:
type: boolean
description: Whether this is a playground session.
proxy_bytes:
type: integer
description: The number of bytes transferred through the proxy.
tokens:
type: object
description: Token usage information.
steps:
type: integer
description: Number of AI agent steps executed in the session.
tags:
type: object
description: Tags associated with the session.
created_at:
type: string
format: date-time
description: The timestamp when the session was created.
'404':
description: Session not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Failed to fetch session.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
delete:
summary: End Browser Session
description: Deletes the browser session associated with the provided browser session ID. Requires a valid API key for authentication.
tags:
- Browser Sessions
parameters:
- in: path
name: session_id
required: true
description: The ID of the browser session to end.
schema:
type: string
security:
- api_key_header: []
responses:
'200':
description: Browser session ended successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'401':
description: Invalid API Key or browser session ID
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/sessions/{session_id}/pages:
get:
summary: Get Browser Session Pages
description: Retrieves a list of pages associated with a specific browser session.
tags:
- Browser Sessions
parameters:
- in: path
name: session_id
required: true
description: The ID of the session to retrieve pages for.
schema:
type: string
security:
- api_key_header: []
responses:
'200':
description: Session pages retrieved successfully.
content:
application/json:
schema:
type: array
items:
type: object
properties:
id:
type: string
description: The unique identifier of the page.
title:
type: string
description: The title of the page.
url:
type: string
description: The URL of the page.
frontend_url:
type: string
description: The frontend URL for accessing the page.
required:
- id
- title
- url
- frontend_url
'401':
description: Invalid API Key or unauthorized access.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: Session not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/sessions/{sessionId}/uploads:
post:
summary: Upload Files
description: 'Upload files directly to a browser session for use with web forms and file inputs.
Files are saved to the session''s uploads directory and can be referenced in CDP commands.
'
security:
- api_key_header: []
tags:
- Browser Sessions
parameters:
- name: sessionId
in: path
required: true
description: The browser session ID
schema:
type: string
format: uuid
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
properties:
file:
type: string
format: binary
description: File to upload to the browser session
responses:
'200':
description: File uploaded successfully
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
status:
type: string
message:
type: string
'400':
description: Invalid request (no file uploaded or file too large)
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: integer
message:
type: string
'404':
description: Session not found
content:
application/json:
schema:
type: object
properties:
error:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Failed to upload file
content:
application/json:
schema:
type: object
properties:
error:
$ref: '#/components/schemas/ErrorResponse'
/v1/sessions/{session_id}/downloads:
get:
summary: List Session Downloads
description: Retrieves metadata of files downloaded during a browser session. Requires a valid API key for authentication.
tags:
- Browser Sessions
parameters:
- in: path
name: session_id
required: true
description: The unique identifier of the browser session to retrieve downloads for.
schema:
type: string
security:
- api_key_header: []
responses:
'200':
description: A list of download metadata associated with the browser session.
content:
application/json:
schema:
$ref: '#/components/schemas/DownloadListResponse'
'401':
description: Invalid or missing API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: The browser session or its downloads metadata could not be found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: Too many requests, please try again later.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
SessionHistoryResponse:
type: object
properties:
data:
type: array
description: Historical data points.
items:
$ref: '#/components/schemas/SessionHistoryDataPoint'
summary:
$ref: '#/components/schemas/SessionHistorySummary'
pagination:
$ref: '#/components/schemas/SessionHistoryPagination'
SuccessResponse:
type: object
properties:
data:
type: object
properties:
status:
type: string
SessionListResponse:
type: object
properties:
data:
type: object
properties:
count:
type: integer
description: Total number of browser sessions
items:
type: array
items:
$ref: '#/components/schemas/SessionStatus'
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'
SessionCreateResponseSchema:
type: object
properties:
data:
type: object
properties:
id:
type: string
description: Unique identifier for the browser session
cdp_url:
type: string
description: The CDP websocket connection string
live_view_url:
type: string
description: The browser session live view url
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
SessionStatus:
type: object
properties:
session_id:
type: string
description: Unique identifier for the browser session
status:
type: string
description: Current status of the browser session
tags:
type: array
items:
type: string
description: Custom labels assigned to this browser session
created_at:
type: string
format: date-time
description: Timestamp when the browser session was created
required:
- session_id
- status
- created_at
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
AsyncSessionStatusResponseSchema:
type: object
description: 'Polling response for `GET /v1/sessions/async/{request_id}/status`.
'
properties:
data:
type: object
required:
- request_id
- status
- created_at
- progress
properties:
request_id:
type: s
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/anchorbrowser/refs/heads/main/openapi/anchorbrowser-browser-sessions-api-openapi.yml