Mouse Move
Browser Sessions
Mouse Move
Move the cursor to coordinates or a CSS selector, dispatching interpolated mousemove events so hover-based UI fires correctly.
POST
Mouse Move
Overview
Dispatches a series ofmousemove 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.
(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).
Error Responses
Notes
- Cursor position is tracked per session. The move starts from the last known cursor position (initially
(0, 0)). A subsequentmouse/clickat a different coord will also update the tracked position, so chainedmove → click → moveflows look continuous. - Interpolation fires the full DOM cascade.
mouseenterandmouseleavefire on every element the cursor crosses, along with intermediatemousemoveevents — necessary for hover-activated menus, tooltips, and many:hoverCSS effects. - For deterministic tests, pass
steps: 1, durationMs: 0to teleport. For scraping hover-triggered UI, stick with the defaults. - Modifier keys are held for every intermediate event, not just the final position.