extract

extract

Read an element's visible text and innerHTML.

MCP tool	extract
HTTP	POST /browser/extract

The primary way to read a page — prefer it over a screenshot, which costs far more. //body reads everything, but a narrower selector keeps the result small.

Address the element with EITHER xpath OR css, never both and never neither.

Parameters

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

Returns

Field	Type	Notes
html	string	innerHTML of the matched element.
text	string	Visible text of the element.
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

extract()

HTTP

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

Notes

This is the default way to read a page. A screenshot of text costs orders of magnitude more, cannot be quoted back, and may be a picture of a page that had not finished rendering. Reach for a capture only when the appearance is the answer.

//body works and is usually the wrong idea. It returns the whole document, navigation and cookie banners included, and on a large page that is most of what you pay for. A narrower XPath is not a nicety — it is the difference between reading a page and reading a site.

html and text differ in ways that matter. text is what a person sees: collapsed whitespace, nothing from hidden elements. html is innerHTML, so it keeps markup, attributes and content that is present but invisible. When a value lives in an attribute rather than in the text, neither helps — use execute_script and return it directly.

An empty result is usually a timing or a frame problem, not an XPath one. The element is waited for, so an empty string means it was found and genuinely holds nothing — but a timeout means it never appeared. Two common reasons: the content renders after an XHR that has not landed, or it lives inside an iframe, where no locator can see it until frame has switched in.

Reading many things is one script, not many extracts. Each call is a round trip to the Grid. execute_script returning an array of the values you want costs one.

---

← All actions · Installing · Deployment