screenshot - kubed-io/selenium-flow GitHub Wiki
Capture a PNG of the viewport, of one element (selector), or of the whole
| MCP tool | screenshot |
| HTTP | POST /browser/screenshot |
page (full_page), returned as an image. Use it only when the look is the answer; extract reads content far more cheaply.
By default the capture is also kept with the workspace's files. To show a person what you saw, give them the file's url: it opens in any browser without a token, and works. Do not describe the image instead.
save=false stores nothing; file_error says why a save failed, and the image still comes back.
| Name | Type | Required | Default |
|---|---|---|---|
url |
string | no | โ |
selector |
Selector | no | โ |
full_page |
boolean | no | false |
width |
integer | no | โ |
height |
integer | no | โ |
wait_timeout |
integer | no | 30 |
save |
boolean | no | true |
filename |
string | no | โ |
Every call names its workspace: an X-Workspace header, or
?workspace=<name>. Sending both is refused. See Workspaces.
| Field | Type | Notes |
|---|---|---|
image |
string | Base64 PNG. |
width |
integer | Image width in pixels. |
height |
integer | Image height in pixels. |
bytes |
integer | Decoded size. A value near zero means a blank capture. |
file |
FileEntry | |
file_error |
string | Present instead of file when the capture could not be kept. The image is still returned. |
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
screenshot()
HTTP
curl -X POST $SELENIUM_FLOW/browser/screenshot \
-H "Authorization: Bearer $TOKEN" \
-H "X-Workspace: $WORKSPACE"Reach for extract first. An image of text costs orders of
magnitude more than the text, cannot be quoted, and may be a picture of a
half-rendered page. Screenshot when the appearance is the answer โ layout,
styling, a chart that only exists once rendered.
bytes is the blank-capture check. A capture of a page that never painted
still returns a valid PNG; it is just small. Comparing bytes against a floor
of a couple of thousand catches that, and is far more reliable than checking a
particular expected size โ a full-page capture of a mostly-white page is only
about 10KB, so a tight threshold goes flaky on a rendering difference.
width/height leave the window resized. They are a resize, not a capture
option, and everything afterwards sees the new size. full_page is different:
it grows the window to the document height for the capture and puts it back.
Whether the caller can see it depends on the client. MCP returns a real
image content block, and Claude Code and Claude Desktop render it. Several
clients do not, and n8n's agent cannot see one at all โ the base64 rides along in
the tool message costing ~18k tokens for nothing. When a person will look at the
result, give them the saved file's url โ it opens in any browser and
needs no bearer token, and it is signed and time-limited when the server has a
token to sign with. Screenshots are kept by default, on any page, so the link is
normally there; save=false opts out, and a server with no DATA_DIR
returns file_error and the image instead.