Skip to main content

​
GET /tabs/:id/stats

Returns detailed statistics about a tab’s activity, including tool call count, visited URLs, and session information.

​
Authentication

Requires userId as a query parameter. Returns 404 if the tab doesn’t exist or belongs to a different user.

​
Request

​
Path parameters

​
id
string
required
The tabId returned when creating the tab via POST /tabs.

​
Query parameters

​
userId
string
required
User identifier. Must match the user who owns the tab.

​
Response

​
tabId
string
UUID identifier for the tab.
​
sessionKey
string
Session key (task/conversation group) this tab belongs to.
​
listItemId
string
Deprecated. Same as sessionKey. Included for backward compatibility.
​
url
string
Current URL of the tab.
​
visitedUrls
array
Array of all URLs visited in this tab (chronological order). Includes URLs from navigation, clicks, and redirects.
​
toolCalls
number
Number of API operations performed on this tab. Includes navigate, click, type, scroll, snapshot, and other actions.
​
refsCount
number
Number of interactive element references currently available on the page. Refs are generated by /snapshot and reset on navigation.

​
Example

curl http://localhost:9377/tabs/f47ac10b-58cc-4372-a567-0e02b2c3d479/stats?userId=agent1
Response: 
{
  "tabId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "sessionKey": "task123",
  "listItemId": "task123",
  "url": "https://example.com/page2",
  "visitedUrls": [
    "https://example.com",
    "https://example.com/page1",
    "https://example.com/page2"
  ],
  "toolCalls": 7,
  "refsCount": 42
}

​
Error responses

StatusErrorCause
400userId requiredMissing userId query parameter
404Tab not foundTab doesn’t exist, was closed, or belongs to different user
500Internal server errorTab state retrieval failure

​
Notes

  • Tool calls increment on every API operation: navigate, snapshot, click, type, scroll, back, forward, refresh, links, and press
  • Visited URLs are tracked in a Set (duplicates removed) and returned as an array
  • refsCount reflects the number of interactive elements (buttons, links, inputs) on the current page
  • Refs reset to 0 after navigation until the next /snapshot call
  • Tab not found errors occur if:
    • The tab was explicitly closed via DELETE /tabs/:id
    • The tab’s session expired (30 minutes of inactivity)
    • The userId doesn’t match the tab owner

Build docs developers (and LLMs) love

Get started for freeTalk to us