---
title: "Create a profile setup session"
method: POST
path: "/v1/profiles/{profileId}/setup-session"
tags: ["Browser Context Profiles"]
---

# Create a profile setup session

`POST /v1/profiles/{profileId}/setup-session`

## Request

- Base URL: `https://agent.tinyfish.ai`
- URL: `https://agent.tinyfish.ai/v1/profiles/{profileId}/setup-session`
- Auth: API key in header `X-API-Key`

Starts a temporary setup browser for a Browser Context Profile. The response returns session_id, cdp_url, base_url, timeout_seconds, and expires_at. Connect your Playwright, Puppeteer, or CDP client to cdp_url, log in, then save the setup session with session_id. Unsaved setup state is discarded if the session is cancelled or times out.

## Path parameters

- `profileId` string, required: Browser Context Profile ID

## Request body

- object: Browser session creation parameters
  - `url` string: Target URL the browser session will navigate to on startup. Bare domains (e.g. tinyfish.ai) are automatically prefixed with https://. If omitted, the browser starts at about:blank.
  - `timeout_seconds` integer, nullable: Inactivity timeout in seconds (5–86400). If omitted, null, or greater than your plan maximum, the plan maximum is used.

## Response `201`

Create a profile setup session succeeded.

- object
  - `session_id` string, required: Unique identifier for this browser session.
  - `cdp_url` string, uri, required: WebSocket URL for browser connection. Pass this to Playwright's connect_over_cdp or any WebSocket-based CDP client.
  - `base_url` string, uri, required: HTTPS base URL for the session. Use to access session endpoints such as /pages.
  - `timeout_seconds` integer, required
  - `expires_at` string, required

## Other responses

- `400`: Invalid request body or profile state too large.
- `401`: Unauthorized - Invalid or missing API key
- `404`: Browser Context Profile not found.
- `409`: Setup session cleanup or binding conflict; retry shortly.
- `500`: Internal server error

---

[API](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2.md) · [All operations](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api-2/revisions/c48ef855099d?raw)