screenshot

screenshot

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 session's files. To show a person what you saw, give them the file's absolute_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.

Parameters

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 session: an X-Session-Key header, or ?session=<name>. Sending both is refused. See Sessions.

Returns

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.

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

screenshot()

HTTP

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

Notes

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 absolute_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 FLOW_DATA_DIR returns file_error and the image instead.

---

← All actions · Installing · Deployment