Skip to main content
POST
/
v1
/
sessions
/
{id}
/
state
Capture State
curl --request POST \
  --url https://api.bctrl.ai/v1/sessions/{id}/state \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ref": "<string>",
  "include": [
    "<string>"
  ],
  "screenshot": {
    "fullPage": true,
    "type": "<string>",
    "quality": 123,
    "maxBytes": 123
  },
  "dom": {
    "includeHtml": true,
    "maxChars": 123
  }
}
'
{
  "sessionId": "<string>",
  "capturedAt": "<string>",
  "driver": {},
  "refResolved": {},
  "meta": {
    "url": {},
    "title": {},
    "readyState": {}
  },
  "dom": {
    "html": "<string>",
    "length": 123
  },
  "screenshot": {
    "mimeType": "<string>",
    "base64": "<string>",
    "bytes": 123,
    "truncated": true
  },
  "warnings": [
    "<string>"
  ]
}
​
id
string
required
Session ID.
​
ref
string
Page or context alias/ID to capture. Defaults to the active page.
​
include
string[]
What to capture: meta, dom, screenshot. Default: ["meta"].
​
screenshot
object
Screenshot options (when screenshot is in include).
​
dom
object
DOM capture options (when dom is in include).
The state endpoint works with any connected driver (Playwright, Puppeteer, Selenium, Stagehand). It adapts to the driver’s available APIs automatically.

​
Examples

// Capture page metadata + screenshot
const response = await fetch(
  `https://api.bctrl.ai/v1/sessions/${sessionId}/state`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      include: ['meta', 'screenshot'],
      screenshot: { type: 'jpeg', quality: 80 },
    }),
  }
);
const state = await response.json();
console.log(state.meta.url, state.meta.title);

​
Response

​
sessionId
string
required
Session ID.
​
capturedAt
string
required
When the snapshot was taken (ISO-8601).
​
driver
string | null
required
Active driver at capture time.
​
refResolved
string | null
Resolved page/context ID if ref was provided.
​
meta
object
Page metadata (when meta is in include).
​
dom
object
DOM content (when dom is in include).
​
screenshot
object
Screenshot data (when screenshot is in include).
​
warnings
string[]
Advisory messages (e.g. truncation notices).
Response Example
{
  "sessionId": "sess_abc123",
  "capturedAt": "2025-01-15T10:00:05Z",
  "driver": "playwright",
  "refResolved": null,
  "meta": {
    "url": "https://example.com/dashboard",
    "title": "Dashboard - Example",
    "readyState": "complete"
  },
  "dom": {
    "html": "<!DOCTYPE html><html>...</html>",
    "length": 45230
  },
  "screenshot": {
    "mimeType": "image/jpeg",
    "base64": "/9j/4AAQ...",
    "bytes": 125000,
    "truncated": false
  }
}