frame

frame

Move into an iframe, or back out of it.

MCP tool	frame
HTTP	POST /browser/frame

action is one of: switch, parent, default. Use switch with an xpath (or index) to go into a frame, parent to go up one level, and default to return to the main page.

Selenium does not look inside frames: an element in one is invisible to every locator until you switch in. The switch sticks — every later call stays in that frame until you switch back, so if a locator that should work is failing, check session://current for in_frame.

Name the frame with xpath, css or index — one of the three, not two. parent and default take none of them.

Parameters

Name	Type	Required	Default	Notes
action	string	no	switch
xpath	string	no	—
css	string	no	—
index	integer	no	—
session_id	string	yes over HTTP	—	The session_id returned by /browser/open. Required here.
wait_timeout	integer	no	30

Returns

Field	Type	Notes
action	string	The switch that was performed.
in_frame	boolean	Whether the session is now inside a frame.
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

frame()

HTTP

curl -X POST $SELENIUM_FLOW/browser/frame \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "session_id": "…"
  }'

---

← All actions · Installing · Deployment