Get snapshot

Retrieve the accessibility tree snapshot of the current page with element references

Endpoint

GET /tabs/:tabId/snapshot

Returns the current page’s accessibility tree as a text snapshot with interactive element references (e1, e2, etc.) that can be used for clicking and typing.

Authentication

No authentication required. All endpoints use userId for session isolation.

Path parameters

tabId · string · required

The unique identifier of the tab

Query parameters

userId · string · required

User identifier for session isolation

includeScreenshot · boolean · default: "false"

Whether to include a base64-encoded PNG screenshot in the response

offset · integer · default: "0"

Character offset for pagination. Use nextOffset from previous response to fetch next chunk.

format · string · default: "text"

Response format (currently only text is supported)

Response

url · string

The current URL of the tab

snapshot · string

Accessibility tree snapshot with element references in YAML-like format. Interactive elements are annotated with refs like [e1], [e2].

refsCount · integer

Total number of interactive element references available

truncated · boolean

Whether the snapshot was truncated due to size limits

totalChars · integer

Total character count of the full snapshot (before truncation)

hasMore · boolean

Whether more content is available beyond the current chunk

nextOffset · integer

Character offset to use for fetching the next chunk (only present if hasMore is true)

screenshot · object

Screenshot data (only present if includeScreenshot=true)

Show Screenshot fields

data · string

Base64-encoded PNG image data

mimeType · string

Always image/png

Pagination

Large pages are automatically truncated to prevent token overflow. The snapshot is limited to 80,000 characters (~20K tokens), with the last 5,000 characters preserved for pagination/navigation links.

• First request: offset=0 returns the head of the snapshot plus tail (pagination links)
• Subsequent requests: Use nextOffset value from the previous response
• The tail (last 5K chars) is appended to every chunk so navigation refs remain accessible

Element references

Interactive elements (buttons, links, textboxes, checkboxes, etc.) are annotated with refs:

- button "Submit" [e1]
- link "More information..." [e2]
- textbox "Search" [e3]

These refs can be used with /click and /type endpoints. Refs reset after navigation - always call /snapshot after navigating to get fresh refs.

Error codes

• 400 - Missing required parameter (userId)
• 404 - Tab not found
• 500 - Internal server error

Examples

Basic snapshot

curl "http://localhost:9377/tabs/abc123/snapshot?userId=agent1"

{
  "url": "https://example.com",
  "snapshot": "- heading \"Example Domain\"\n- paragraph \"This domain is for use in illustrative examples...\"\n- link \"More information...\" [e1]\n",
  "refsCount": 1,
  "truncated": false,
  "totalChars": 156,
  "hasMore": false,
  "nextOffset": null
}

Snapshot with screenshot

curl "http://localhost:9377/tabs/abc123/snapshot?userId=agent1&includeScreenshot=true"

{
  "url": "https://example.com",
  "snapshot": "- heading \"Example Domain\"...",
  "refsCount": 1,
  "truncated": false,
  "totalChars": 156,
  "hasMore": false,
  "nextOffset": null,
  "screenshot": {
    "data": "iVBORw0KGgoAAAANSUhEUgAAA...",
    "mimeType": "image/png"
  }
}

Paginated snapshot

# First chunk
curl "http://localhost:9377/tabs/abc123/snapshot?userId=agent1"

{
  "url": "https://longpage.com",
  "snapshot": "[content]\n[... truncated at char 75000 of 120000. Call snapshot with offset=75000 to see more. Pagination links below. ...]\n[tail content with pagination links]",
  "refsCount": 245,
  "truncated": true,
  "totalChars": 120000,
  "hasMore": true,
  "nextOffset": 75000
}

# Next chunk
curl "http://localhost:9377/tabs/abc123/snapshot?userId=agent1&offset=75000"

Caching behavior

For offset > 0 requests, the server uses a cached snapshot from the last offset=0 call. This ensures consistent pagination without rebuilding the accessibility tree. The cache is invalidated after navigation or interaction.

Excluded elements

The following elements are excluded from snapshots to avoid interference:

• Comboboxes (date pickers, complex dropdowns)
• Elements matching patterns: date, calendar, picker, datepicker

This prevents accidental triggering of complex widgets during automation.