Skip to main content

​
Endpoint

POST /tabs/:tabId/click
Clicks an element on the page using either an element reference from the snapshot or a CSS selector.

​
Authentication

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

​
Path parameters

​
tabId
string
required
The unique identifier of the tab

​
Body parameters

​
userId
string
required
User identifier for session isolation
​
ref
string
Element reference from snapshot (e.g., e1, e2). Either ref or selector is required.
​
selector
string
CSS selector for the target element. Either ref or selector is required.
​
timeout
integer
default:"5000"
Maximum time in milliseconds to wait for the element to become clickable

​
Response

​
ok
boolean
Always true on success
​
url
string
The URL after the click (may differ if navigation occurred)
​
refsAvailable
boolean
Whether element references were successfully rebuilt after the click

​
Click behavior

The endpoint implements a three-tier fallback strategy to handle stubborn elements:
  1. Normal click: Respects visibility, enabled state, and obscuration checks
  2. Force click: If intercepted by overlay (e.g., consent dialog), retries with force flag
  3. Mouse sequence: If click fails, dispatches full mouse event sequence: mouseover → mouseenter → mousedown → mouseup → click
After a successful click:
  • Waits 500ms for UI updates
  • Rebuilds element references
  • Updates the current URL

​
Element reference handling

When using ref parameter:
  • If refs are stale (empty), they’re automatically refreshed before the click
  • Duplicate role+name combinations are disambiguated using .nth() based on document order
  • Refs reset after navigation - call /snapshot first to get fresh refs

​
Error codes

  • 400 - Missing required parameter (userId, or both ref and selector)
  • 404 - Tab not found
  • 500 - Click failed (element not found, timeout, unknown ref)

​
Error messages

  • Unknown ref: Unknown ref: e99 (valid refs: e1-e50, 50 total). Refs reset after navigation - call snapshot first.
  • Element not found: Element not visible (no bounding box)
  • Timeout: Timeout 5000ms exceeded

​
Examples

​
Click by reference

curl -X POST http://localhost:9377/tabs/abc123/click \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agent1",
    "ref": "e1"
  }'

{
  "ok": true,
  "url": "https://example.com/next-page",
  "refsAvailable": true
}

​
Click by CSS selector

curl -X POST http://localhost:9377/tabs/abc123/click \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agent1",
    "selector": "button.submit-btn"
  }'

{
  "ok": true,
  "url": "https://example.com",
  "refsAvailable": true
}

​
Click with custom timeout

curl -X POST http://localhost:9377/tabs/abc123/click \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agent1",
    "ref": "e5",
    "timeout": 10000
  }'

​
Error: Unknown ref

curl -X POST http://localhost:9377/tabs/abc123/click \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "agent1",
    "ref": "e999"
  }'

{
  "error": "Unknown ref: e999 (valid refs: e1-e24, 24 total). Refs reset after navigation - call snapshot first."
}

​
Tab locking

Click operations are serialized per tab to prevent race conditions. If another operation is in progress, the request will wait up to 30 seconds before proceeding.

​
Best practices

  1. Always call /snapshot after navigation to refresh element refs
  2. Use ref (not selector) when possible - refs are more stable and semantic
  3. For dynamically loaded content, increase the timeout value
  4. Check refsAvailable in the response - if false, call /snapshot before next interaction

Build docs developers (and LLMs) love

Get started for freeTalk to us