Skip to main content

​
GET /tabs

Returns all open browser tabs for the specified user, grouped by session key. Returns an empty array if the user has no active session.

​
Authentication

Requires userId as a query parameter to identify which user’s tabs to list.

​
Request

​
Query parameters

​
userId
string
required
User identifier. Returns tabs only for this user’s session.

​
Response

​
running
boolean
Always true when the server is operational.
​
tabs
array
Array of tab objects. Empty if user has no session or no open tabs.

​
Example

curl http://localhost:9377/tabs?userId=agent1
Response: 
{
  "running": true,
  "tabs": [
    {
      "targetId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "tabId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "url": "https://example.com",
      "title": "Example Domain",
      "listItemId": "task123"
    },
    {
      "targetId": "8b3d5e7a-9c2f-4a6b-b8e1-3f5a7c9d1e2b",
      "tabId": "8b3d5e7a-9c2f-4a6b-b8e1-3f5a7c9d1e2b",
      "url": "https://google.com",
      "title": "Google",
      "listItemId": "task456"
    }
  ]
}
No active session: 
{
  "running": true,
  "tabs": []
}

​
Error responses

StatusErrorCause
500Internal server errorTab state retrieval failure

​
Notes

  • Returns tabs across all session keys for the specified user
  • Does not require an active session - returns empty array if user has no tabs
  • Tab titles are fetched asynchronously and may be empty if the page hasn’t loaded
  • The targetId field is included for compatibility with OpenClaw’s browser tool
  • Maximum tabs per session: 10 (configurable via MAX_TABS_PER_SESSION)
  • Global maximum across all users: 100 tabs (configurable via MAX_TABS_GLOBAL)

Build docs developers (and LLMs) love

Get started for freeTalk to us