Skip to main content
POST
/
browser
/
sessions
/
{id}
/
mouse
/
click
Mouse Click
curl --request POST \
  --url https://api.example.com/browser/sessions/{id}/mouse/click \
  --header 'Content-Type: application/json' \
  --data '
{
  "x": 123,
  "y": 123,
  "selector": "<string>",
  "timeout": 123,
  "index": 123,
  "button": "<string>",
  "holdKeys": [
    "<string>"
  ],
  "numClicks": 123
}
'
{
  "x": 123,
  "y": 123
}

​
Overview

The /browser/sessions/{id}/mouse/click endpoint dispatches a mouse click against the currently active page inside a browser session. It supports two modes:
  • Coordinates — click at (x, y) in viewport CSS pixels.
  • Selector — click the center of an element matched by a CSS selector. Waits for the element to be visible.
The two modes are mutually exclusive. Pass either (x, y) or selector, never both.

​
Path Parameters

​
id
string
required
Browser session ID (UUID). Create via POST /browser/sessions.

​
Body

​
x
integer
X coordinate in viewport CSS pixels. Required together with y when selector is omitted.
​
y
integer
Y coordinate in viewport CSS pixels. Required together with x when selector is omitted.
​
selector
string
CSS selector of the element to click. Mutually exclusive with x/y. Clicks the center of the element’s bounding box.
​
timeout
integer
default:"5000"
How long to wait (ms) for the selector to become visible. Ignored when using coordinates.
​
index
integer
default:"0"
Which match to click when the selector resolves to multiple elements (0-based).
​
button
string
default:"left"
Mouse button to press. One of left, right, middle, back, forward. The back and forward buttons map to the side buttons used for browser navigation on some sites.
​
holdKeys
string[]
Modifier keys held for the duration of the click. Each value must be one of Shift, Control, Alt, Meta.
​
numClicks
integer
default:"1"
Number of clicks to issue at the same point. Capped at 10.

​
Example Request

curl -X POST "https://api.scrapengine.io/api/v1/browser/sessions/0f2b1f6a-88ac-4d25-bc58-67a6f4b4a001/mouse/click" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "x": 120,
    "y": 240,
    "button": "left"
  }'

​
Response

​
Success Response (200)

​
x
integer
X coordinate actually clicked (in viewport CSS pixels). For selector mode, this is the center of the resolved element.
​
y
integer
Y coordinate actually clicked (in viewport CSS pixels).
Example Response: 
{
  "x": 120,
  "y": 240
}

​
Error Responses

StatusDescription
400Invalid body — both coordinate and selector modes supplied, selector didn’t match, unknown button/modifier, or numClicks out of range.
401Unauthorized — invalid or missing API key.
404Session not found or not owned by the caller.
503The browser session is temporarily unreachable.

​
Notes

  • Coordinate system: coordinates are viewport-relative in CSS pixels. On HiDPI pages, they do not need to be scaled by devicePixelRatio — the browser handles that internally.
  • Selector mode: the endpoint waits up to timeout ms for the first match to become visible, then clicks the center of its bounding box. Use index to target the Nth match.
  • Modifiers: holdKeys are held for the full duration of every click in a multi-click sequence.