Sessions

A browser session is an isolated, short-lived Chromium instance with network access restricted to the domains you allow.

Create a Session

curl -X POST https://api.telnyx.com/v2/browser_sessions \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "policy": {
      "allowed_domains": ["example.com", "*.example.com"]
    },
    "limits": {
      "lifetime_s": 600,
      "idle_timeout_s": 120
    }
  }'

Policy

Field	Type	Required	Description
`allowed_domains`	string[]	Yes	1–50 domain patterns the browser can navigate to.

allowed_domains Matching

Matching is exact-only — no implicit subdomain matching.

Pattern	Matches	Does NOT match
`example.com`	`example.com`	`www.example.com`, `api.example.com`
`*.example.com`	`www.example.com`, `api.example.com`	`example.com` (the apex)
`wikipedia.org`	`wikipedia.org`	`en.wikipedia.org`, `www.wikipedia.org`
`*.wikipedia.org`	`en.wikipedia.org`, `www.wikipedia.org`	`wikipedia.org` (the apex)

To allow a domain and all its subdomains, list both:

{ "policy": { "allowed_domains": ["wikipedia.org", "*.wikipedia.org"] } }

Wildcard patterns use *. prefix — *.example.com matches any subdomain but not the apex itself.
Exact patterns (example.com) match only that exact hostname.
IP literals (e.g. 127.0.0.1) are not allowed.

Limits

Field	Type	Default	Min	Max	Description
`lifetime_s`	int	900	60	1800	Max session duration in seconds. Values above 1800 are rejected (400).
`idle_timeout_s`	int	300	30	— (≤ `lifetime_s`)	Idle timeout in seconds. Must not exceed `lifetime_s`.

Idempotency and Concurrent-Session Quota

Pass an optional idempotency_key (1–255 characters) in the create request body. Within the same organization, the same key and identical normalized policy, limits, and metadata return the existing session with HTTP 201. Defaults are applied before comparison. A different request with that key returns 409 idempotency_conflict. A replay does not restart a closed, failed, or expired session. Creating a new session can return 429 quota_exceeded with retryable: true when the organization’s concurrent-session quota is reached. Close unneeded active sessions or wait for capacity before trying again. This is a session quota, not a per-key request-rate limit.

Session Lifecycle

Status	Description
`provisioning`	Session is starting up.
`ready`	Browser is up and accepting actions.
`closing`	Session is being shut down.
`closed`	Session closed, resources released.
`failed`	Session failed (see `failure_reason`, e.g. `provision_timeout` when the session could not start).
`expired`	Session exceeded its lifetime or idle timeout.

List Sessions

curl -s https://api.telnyx.com/v2/browser_sessions?status=ready \
  -H "Authorization: Bearer ***"

Filter by status: provisioning, ready, closing, closed, failed, expired.

Get Session

curl -s https://api.telnyx.com/v2/browser_sessions/$SESSION_ID \
  -H "Authorization: Bearer ***"

Close Session

curl -X DELETE https://api.telnyx.com/v2/browser_sessions/$SESSION_ID \
  -H "Authorization: Bearer ***"

Closing a ready session normally returns status: "closed". An already closed, failed, or expired session is returned unchanged. A provisioning session returns 409 session_not_ready; poll its state before closing again. A request that cannot be completed reliably can return 503 execution_lost with retryable: true; retrieve the session state before retrying the close.

Agent Browser

Features

API Reference

For AI Agents

Create a Session

Policy

allowed_domains Matching

Limits

Idempotency and Concurrent-Session Quota

Session Lifecycle

List Sessions

Get Session

Close Session

​Create a Session

​Policy

​allowed_domains Matching

​Limits

​Idempotency and Concurrent-Session Quota

​Session Lifecycle

​List Sessions

​Get Session

​Close Session

Create a Session

Policy

allowed_domains Matching

Limits

Idempotency and Concurrent-Session Quota

Session Lifecycle

List Sessions

Get Session

Close Session