Get tab statistics

Retrieve usage statistics and metadata for a specific tab

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

Status	Error	Cause
400	userId required	Missing userId query parameter
404	Tab not found	Tab doesn’t exist, was closed, or belongs to different user
500	Internal server error	Tab 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