---
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`

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.md) · [All operations](https://skmtc.dev/tinyfish/apis/tinyfish-web-agent-automation-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/tinyfish/tinyfish-web-agent-automation-api/revisions/bea716bc627d/schema)