Skip to main content
POST
Mouse Move

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

string
required
Browser session ID (UUID).

Body

integer
X coordinate in viewport CSS pixels. Required together with y when selector is omitted.
integer
Y coordinate in viewport CSS pixels. Required together with x when selector is omitted.
string
CSS selector of the element to hover. Mutually exclusive with x/y. Moves to the center of the element’s bounding box.
integer
default:"5000"
How long to wait (ms) for the selector to become visible. Ignored when using coordinates.
integer
default:"0"
Which match to target when the selector resolves to multiple elements (0-based).
string[]
Modifier keys held for the duration of the move. Each value must be one of Shift, Control, Alt, Meta.
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.
integer
default:"150"
Total time (ms) to complete the move. Step delay is durationMs / steps.

Example Request

Response

Success Response (200)

integer
X coordinate the cursor landed on (in viewport CSS pixels). For selector mode, this is the center of the resolved element.
integer
Y coordinate the cursor landed on (in viewport CSS pixels).
Example Response:

Error Responses

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.