---
title: "Create browser session"
method: POST
path: "/browser_sessions"
tags: ["Browser Sessions"]
---

# Create browser session

`POST /browser_sessions`

## Request

- Base URL: `https://api.telnyx.com/v2`
- URL: `https://api.telnyx.com/v2/browser_sessions`
- Auth: HTTP bearer

Creates an isolated browser session with network access restricted to the domains you allow.

## Request body

- CreateSessionRequest
  - `policy` object, required
    - `allowed_domains` string[], required: Domain patterns the browser can navigate to. Exact match (example.com) or wildcard (*.example.com). IP literals not allowed.
  - `limits` object
    - `lifetime_s` integer: Max session duration in seconds (60-1800).
    - `idle_timeout_s` integer: Idle timeout in seconds. Must not exceed lifetime_s.
  - `metadata` object: Arbitrary key-value metadata.
  - `idempotency_key` string: Scoped to the organization. The same key and identical normalized policy, limits, and metadata replay the existing session (HTTP 201); a different request returns 409 idempotency_conflict. Replays do not restart terminal sessions.

## Response `201`

Session created

- object
  - `data` Session
    - `id` string, required
    - `status` 'provisioning' | 'ready' | 'closing' | 'closed' | 'failed' | 'expired', required
    - `failure_reason` string, nullable, required
    - `policy` object, required
      - `allowed_domains` string[], required
    - `limits` object, required
      - `lifetime_s` integer, required
      - `idle_timeout_s` integer, required
    - `metadata` object, required
    - `created_at` string, date-time, required
    - `ready_at` string, date-time, nullable, required
    - `last_activity_at` string, date-time, nullable, required
    - `expires_at` string, date-time, nullable, required
    - `closed_at` string, date-time, nullable, required

## Other responses

- `400`: Invalid request — validation error or invalid parameters.
- `401`: Unauthorized — missing or invalid API key.
- `409`: Idempotency key reused with a different normalized create request.
- `429`: Concurrent-session quota exceeded for the organization. Close unneeded active sessions or wait for capacity before retrying.
- `500`: The session could not be created.

## Changes

> 152 revisions in range; 1 not diffed.

- **2026-10-22** `2961ffd5402d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/browser_sessions/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) - [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/f82938f53ff4?raw)