Sessions

Create, manage, and inspect browser sessions.

POST/api/sessions

Create a new browser session. Returns immediately with status 'creating' while the cloud browser provisions.

Body Parameters

initialPromptstringNavigate to URL or run AI task on startup

options.browserstringBrowser engine: chromium (default)

options.viewportobject{ width, height } viewport size

Response

{
  "sessionId": "session-abc123",
  "status": "creating",
  "machineId": "d8901234"
}

GET/api/sessions

List sessions for the authenticated user. Supports pagination with limit/offset.

Query Parameters

limitintegerResults per page, 1–100 (default 30)

offsetintegerSkip N results (default 0)

includeTerminatedbooleanInclude completed/failed/cancelled sessions (default false)

Response

{
  "sessions": [
    {
      "sessionId": "session-abc123",
      "status": "running",
      "currentUrl": "https://example.com",
      "createdAt": "2026-03-01T10:00:00Z",
      "navigationCount": 5
    }
  ],
  "total": 42,
  "hasMore": true
}

GET/api/sessions/:sessionId

Get details for a specific session including navigation history and action count.

Response

{
  "sessionId": "session-abc123",
  "status": "running",
  "currentUrl": "https://example.com",
  "title": "Example Domain",
  "actionCount": 15,
  "screenshotCount": 3,
  "duration": 45000
}

DELETE/api/sessions/:sessionId

Terminate a session and destroy the cloud browser. Artifacts (screenshots, recordings) are preserved.

Response

{
  "success": true,
  "message": "Session terminated"
}

GET/api/sessions/:sessionId/actions

Get the action log for a session. Returns all actions with timestamps, success status, and cost data.

Query Parameters

offsetnumberSkip first N actions (default: 0)

limitnumberMax actions to return (default: 100)

Response

{
  "actions": [
    {
      "type": "navigate",
      "timestamp": "2026-02-09T12:00:01Z",
      "success": true,
      "details": { "url": "https://example.com" },
      "duration": 1200
    }
  ],
  "total": 15
}

GET/api/sessions/:sessionId/artifacts

List all artifacts (screenshots, recordings) for a session with signed download URLs.

Response

{
  "artifacts": [
    {
      "objectId": "obj-123",
      "type": "screenshot",
      "publicUrl": "https://storage.example.com/...",
      "timestamp": "2026-02-09T12:00:05Z"
    }
  ]
}

GET/api/sessions/:sessionId/health

Health check for a specific session. Returns session state and browser responsiveness.

Response

{
  "status": "healthy",
  "sessionState": "running",
  "browserResponsive": true,
  "currentUrl": "https://example.com",
  "uptimeMs": 45000
}

GET/api/sessions/:sessionId/console

Get console log entries captured during the session.

Response

{
  "logs": [
    {
      "level": "log",
      "message": "Page loaded",
      "timestamp": "2026-02-09T12:00:02Z"
    },
    {
      "level": "error",
      "message": "Failed to load resource",
      "timestamp": "2026-02-09T12:00:03Z"
    }
  ]
}

GET/api/sessions/:sessionId/network

Get network requests captured during the session.

Response

{
  "requests": [
    {
      "url": "https://example.com/api/data",
      "method": "GET",
      "status": 200,
      "duration": 150,
      "size": 4096
    }
  ]
}