drag

drag

Drag one element onto another, or by an offset in pixels.

MCP tool	drag
HTTP	POST /browser/drag

Address the thing being dragged with selector. Say where it goes with EITHER to - a destination element - OR by_x and by_y, a distance from where it started. A range slider is the by_x case; a card into a column is the element case.

The pointer presses, travels and releases, holding briefly at each end because several drag libraries arm on a delay rather than on the press. glide defaults to true here: incremental movement is most of what a drag is for, and a library watching pointermove sees nothing without it.

This drives pointer events, and on Chrome that is also enough for native HTML5 drag-and-drop (dragstart through drop). On Firefox the native drop does not complete - measured, not assumed - so a draggable=true element there may need the page's own fallback.

Parameters

Name	Type	Required	Default
selector	Selector	no	—
to	Selector	no	—
by_x	integer	no	—
by_y	integer	no	—
url	string	no	—
wait_timeout	integer	no	30
glide	boolean	no	true

Every call names its session: an X-Session-Key header, or ?session=<name>. Sending both is refused. See Sessions.

Returns

Field	Type	Notes
from	object	Where the drag started, in viewport pixels.
to	object	Where it was released, in viewport pixels.
glided	boolean	Whether the travel was incremental.
clamped	string	Present when the destination was outside the window, so the drag stopped at its edge.
url	string	Current URL after the action.
title	string	Page title after the action.

Errors

Status	Means
400	The request cannot succeed as sent — a missing field, a value that was rejected, or a locator that matched nothing before the wait ran out. Do not retry it unchanged.
401	Missing or wrong bearer token.
404	No such browser session. It ended, the Grid reaped it, or the id was never real. Open a new one and retry.
500	Something failed that this server did not expect.
503	The Grid could not serve this — unreachable, or no free slot for a new browser. Worth retrying after a wait.

Over MCP the same failures arrive as a tool error.

Example

MCP

drag()

HTTP

curl -X POST $SELENIUM_FLOW/browser/drag \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Session-Key: $SESSION"

---

← All actions · Installing · Deployment