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

​
Overview

Dispatches a series of mousemove events along a straight line from the cursor’s previous position to the target, so the DOM sees a realistic mouseenter / mousemove / mouseleave cascade on every element the cursor passes over. The endpoint supports two modes:
  • Coordinates — move to (x, y) in viewport CSS pixels.
  • Selector — move to the center of the element matched by a CSS selector. Waits for visibility.
The two modes are mutually exclusive. Pass either (x, y) or selector, never both.

​
Path Parameters

​
id
string
required
Browser session ID (UUID).

​
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 hover. Mutually exclusive with x/y. Moves to 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 target when the selector resolves to multiple elements (0-based).
​
holdKeys
string[]
Modifier keys held for the duration of the move. Each value must be one of Shift, Control, Alt, Meta.
​
steps
integer
default:"10"
Number of intermediate mousemove events dispatched along the path. 1 teleports — useful for deterministic tests, but does not fire mouseenter / mousemove on elements in between. Capped at 100.
​
durationMs
integer
default:"150"
Total time (ms) to complete the move. Step delay is durationMs / steps.

​
Example Request

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

​
Response

​
Success Response (200)

​
x
integer
X coordinate the cursor landed on (in viewport CSS pixels). For selector mode, this is the center of the resolved element.
​
y
integer
Y coordinate the cursor landed on (in viewport CSS pixels).
Example Response: 
{
  "x": 400,
  "y": 300
}

​
Error Responses

StatusDescription
400Invalid body — both modes provided, neither provided, steps/durationMs out of range, bad modifier.
401Unauthorized — invalid or missing API key.
404Session not found, or selector did not become visible before timeout.
503The browser session is temporarily unreachable.

​
Notes

  • Cursor position is tracked per session. The move starts from the last known cursor position (initially (0, 0)). A subsequent mouse/click at a different coord will also update the tracked position, so chained move → click → move flows look continuous.
  • Interpolation fires the full DOM cascade. mouseenter and mouseleave fire on every element the cursor crosses, along with intermediate mousemove events — necessary for hover-activated menus, tooltips, and many :hover CSS effects.
  • For deterministic tests, pass steps: 1, durationMs: 0 to teleport. For scraping hover-triggered UI, stick with the defaults.
  • Modifier keys are held for every intermediate event, not just the final position.