screenshot

screenshot

Capture a PNG of the page and return it as an image you can see.

MCP tool	screenshot
HTTP	POST /browser/screenshot

Three modes: pass xpath (or css) for one element, full_page for the whole scrollable page, or none of them for the visible viewport.

Only reach for this when the visual result matters — layout, styling, a rendered chart. To read content, extract is far cheaper.

Set save to also keep it with the session's files, where it gets a URL that opens in a browser. Worth doing whenever a person will look at it: many clients cannot display an image returned by a tool, and every one of them can follow a link. Saving also returns the file's name, which is what keep_file and session_files take.

Parameters

Name	Type	Required	Default	Notes
session_id	string	yes over HTTP	—	The session_id returned by /browser/open. Required here.
url	string	no	—
xpath	string	no	—
css	string	no	—
full_page	boolean	no	false
width	integer	no	—
height	integer	no	—
wait_timeout	integer	no	30
save	boolean	no	false
filename	string	no	—

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	object	The stored file, as the Grid's download store lists it.
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 'Content-Type: application/json' \
  -d '{
    "session_id": "…"
  }'

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, pass save=true and give them the link.

---

← All actions · Installing · Deployment