---
title: "Create Session"
method: POST
path: "/tetra/sessions"
tags: ["AgentQL Tetra (Remote Chrome Browser)"]
---

# Create Session

`POST /tetra/sessions`

Create a new Tetra browser session.

## Request body

- BrowserRequest — Request model for browser session
  - `browser_ua_preset` 'windows' | 'macos' | 'linux'
  - `browser_profile` 'light' | 'stealth' | 'tf-browser' — Browser profile types. LIGHT provides fast headless browsing for standard automation. STEALTH provides enhanced anti-detection capabilities with full browser features TF_BROWSER provides agent-focused capabilities with full browser features.
  - `profile_id` string, nullable — ID of a saved browser profile (auth state) to attach for save-back and future hydration; distinct from browser_profile, which selects the browser image.
  - `shutdown_mode` 'on_disconnect' | 'on_inactivity_timeout' — Controls how a browser session is torn down on disconnect.
  - `inactivity_timeout_seconds` integer — The inactivity timeout in seconds (up to 24h)
  - `proxy` union — Proxy configuration for this browser session
    - TetraProxy — Tetra built-in proxy configuration
      - `type` 'tetra' — Type of proxy: 'tetra' for built-in proxy
      - `country_code` string — Country code for tetra proxy
    - CustomProxy — Custom external proxy configuration
      - `type` 'custom' — Type of proxy: 'custom' for external proxy
      - `url` string, required — Proxy server URL
      - `username` string, nullable — Username for proxy authentication
      - `password` string, nullable — Password for proxy authentication
  - `sub_user_id` string, nullable — Optional sub-user identifier for tracking sessions within a user account
  - `request_origin` string, nullable — Opaque caller-supplied request origin for session attribution
  - `branding` boolean — Whether to show TinyFish branding on the session end screen
  - `browser_startup_url` union — If set, Tetra pre-navigates Chromium to this URL before the CDP client connects (faster prewarming for known target sites). Accepts an http(s) URL or the literal 'about:blank' to pre-open an empty tab.
    - string, uri
    - 'about:blank'

## Response `201`

Successful Response

- BrowserSession — Response model for browser session
  - `session_id` string, required
  - `cdp_url` string, required
  - `base_url` string, required

## Other responses

- `422` — Validation Error

## Changes

> 3 revisions in range; 1 could not be searched.

- **2026-07-26** `4962bfdecf2e` — 1 info
  - added the new optional request property `anyOf[subschema #1: BrowserRequest]/profile_id`

[Change history](https://skmtc.dev/agentql/apis/agentql-api/changes/tetra/sessions/post.md)

---

[API](https://skmtc.dev/agentql/apis/agentql-api.md) · [All operations](https://skmtc.dev/agentql/apis/agentql-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/agentql/agentql-api/revisions/d7edf0ed4272/schema)