Sessions

A session is one running browser instance Driftstack manages for you. This page is the reference for the /v1/sessions surface; for the 60-second walkthrough see api-quickstart.

Lifecycle

State	What it means
`creating`	Backend received the start request; provisioning a browser instance.
`ready`	Browser ready; the session URL is reachable.
`busy`	Session is actively running an automation step.
`destroyed`	Normal end-of-life; session has been torn down.
`errored`	Abnormal termination; the session cannot recover.

Transitions: creating → ready → busy → destroyed is the happy path. errored is terminal; the session cannot recover.

POST /v1/sessions

POST /v1/sessions
Authorization: Bearer ds_live_…
Content-Type: application/json

{
  "archetype": "default",                  ← optional, lowercase slug
  "purpose": "production_customer",        ← optional, default applied server-side
  "label": "ticket-JIRA-1234",             ← optional, ≤120 chars
  "metadata": { "ticket": "JIRA-1234" },   ← optional, surfaced in webhooks
  "profile_id": "prof_01HV…",              ← optional, binds session to a profile
  "behavioral_profile": "regular"          ← optional, persona: casual|regular|power_user
}

→ 201 Created
{
  "id": "ses_…",
  "account_id": "acc_…",
  "api_key_id": "key_…",
  "status": "creating",
  "archetype": "default",
  "purpose": "production_customer",
  "label": "ticket-JIRA-1234",
  "metadata": { "ticket": "JIRA-1234" },
  "created_at": "2026-05-12T12:00:00.000Z",
  "updated_at": "2026-05-12T12:00:00.000Z",
  "last_state_at": null,
  "destroyed_at": null
}

The response is a flat session object — no {"session": …} envelope. Session ids are prefixed ses_. The session moves to ready within ~10 seconds (the driver bootstrap time). Poll GET /v1/sessions/:id or subscribe to the session.completed / session.failed webhooks for status changes.

The create call does not take a target URL. Drive the session to a URL after it reaches ready with POST /v1/sessions/<id>/navigate:

POST /v1/sessions/ses_…/navigate
Authorization: Bearer ds_live_…
Content-Type: application/json

{ "url": "https://example.com", "wait_until": "load" }

GET /v1/sessions/:id

GET /v1/sessions/ses_…
Authorization: Bearer ds_live_…

→ 200 OK
{
  "id": "ses_…",
  "account_id": "acc_…",
  "api_key_id": "key_…",
  "status": "busy",
  "archetype": "default",
  "purpose": "production_customer",
  "label": "ticket-JIRA-1234",
  "metadata": { "ticket": "JIRA-1234" },
  "created_at": "2026-05-12T12:00:00.000Z",
  "updated_at": "2026-05-12T12:00:08.000Z",
  "last_state_at": "2026-05-12T12:00:08.000Z",
  "destroyed_at": null
}

GET /v1/sessions — list

GET /v1/sessions?limit=25
Authorization: Bearer ds_live_…

→ 200 OK
{
  "data": [ /* Session objects, newest first */ ],
  "has_more": true,
  "next_cursor": "eyJ0aWQiOi…"   ← null when no more pages
}

Cursor pagination. Pass the previous response's next_cursor as ?cursor= on the next request. Default page size is 50; max 100.

POST /v1/sessions/:id/capture

POST /v1/sessions/ses_…/capture
Authorization: Bearer ds_live_…
Content-Type: application/json

{ "kind": "screenshot" }

→ 200 OK
{
  "kind": "screenshot",
  "data": "<base64-encoded bytes>",
  "encoding": "base64",
  "byte_size": 184320,
  "duration_ms": 412
}

Captures return inline base64 bytes — there is no presigned URL. kind selects screenshot, dom_snapshot, or pdf. Decode data on the client according to encoding.

DELETE /v1/sessions/:id

DELETE /v1/sessions/ses_…
Authorization: Bearer ds_live_…

→ 204 No Content

Ends the session immediately and transitions it to destroyed. Idempotent — DELETEing an already-destroyed session also returns 204.

Concurrent session limits

Each tier caps the number of sessions you can have in the live states (creating, ready, busy) at once. See rate-limits + the concurrency doc for the per-tier table. Hitting the cap returns 429 Too Many Requests with the concurrency-limit RFC 7807 problem type — wait for an existing session to finish or upgrade your tier.

Webhooks

Subscribe to session.completed + session.failed instead of polling. See /docs/webhooks for the delivery format + signature verification, and the event-types table for the complete list of subscribable events.

Archetype slugs

archetype is a lowercase slug (3–60 chars, [a-z0-9_]) identifying a persona / device profile stored on your account. Mint reusable archetypes via the Profiles API and pass the slug at session create time; for one-shot anonymous sessions, omit the field and the server applies your account's default archetype.

Support

[email protected].