Skip to main content

​
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)

​
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.