Skip to main content
POST
Start a session

Authorizations

Authorization
string
header
required

Secret key (sk_live_...)

Headers

Idempotency-Key
string

Optional key that makes the request idempotent. Retrying with the same key returns the original response instead of repeating the operation; keys expire after 24 hours. Any string up to 256 characters. See Idempotency.

Maximum string length: 256
Example:

"550e8400-e29b-41d4-a716-446655440000"

Body

Request body for starting a session. Every field is optional; an empty body starts a plain session.

source_id
null | string

The source to prepare the session for. The agent opens that source's login page ahead of the first run, so an auth run on this session starts a few seconds ahead. A hint for what the session does next, not a restriction on it: a task or workflow run on the session can target any source, and the session's network path is fixed by the first run that uses it rather than by this field. An unknown source returns 404. Prefixed with src_.

Pattern: ^src_
Example:

"src_AbC123xYz456"

Response

Created

A session object representing an isolated compute session for executing tasks.

id
string
required

Unique identifier for the session, prefixed with sess_.

Pattern: ^sess_
Example:

"sess_AbC123xYz456"

object
string
required

Always session.

status
string
required

Session status: queued, running, idle, completing, completed, or failed.

runtime_ms
required

Total session runtime in milliseconds.

task_runs
object[]
required

Task runs executed within this session.

created_at
string<date-time>
required

ISO 8601 timestamp of when the resource was created.

Example:

"2026-08-24T12:00:00Z"

updated_at
string<date-time>
required

ISO 8601 timestamp of when the resource was last updated.

Example:

"2026-08-24T12:00:00Z"

request_id
string
required

Unique identifier for the API request. Include this when contacting support.

source_id
string

The source the session was prepared for. Present only when a source_id was passed when starting the session. Prefixed with src_.

Pattern: ^src_
Example:

"src_AbC123xYz456"