extract - kubed-io/selenium-flow GitHub Wiki
Read an element's visible text and HTML.
| MCP tool | extract |
| HTTP | POST /browser/extract |
The cheapest way to read a page; prefer it to a screenshot. //body reads everything, and a narrower selector keeps the result small. To find a selector, use outline.
| Name | Type | Required | Default |
|---|---|---|---|
selector |
Selector | no | โ |
url |
string | no | โ |
wait_timeout |
integer | no | 30 |
Every call names its workspace: an X-Workspace header, or
?workspace=<name>. Sending both is refused. See Workspaces.
| 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. |
site_data |
object | Present only when site data was restored, skipped or forgotten in this call. |
page |
object | Present only when this browser was opened with capture=true and the page reported a failure while the call ran: what it caused, and where to read it. |
| 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. |
413 |
The body is over its cap: 1 MiB of JSON, 64 MiB of upload, 1 MiB of flow YAML. Send less; retrying it unchanged will fail again. |
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.
MCP
extract()
HTTP
curl -X POST $SELENIUM_FLOW/browser/extract \
-H "Authorization: Bearer $TOKEN" \
-H "X-Workspace: $WORKSPACE"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.