save_site_data

save_site_data

Save this workspace's site data, so a new browser comes back signed in.

MCP tool	save_site_data
HTTP	POST /browser/save-site-data

It keeps every cookie the browser holds, the localStorage of the sites it has been to, and the sessionStorage of the page it is on. Call it right after a sign-in is confirmed, and after changing a setting you want kept; never before checking you landed, or you keep a failed sign-in.

One save covers every site a call ended on, while the workspace keeps its history (a day by default, 100 sites): one passed through inside a call is not read, and one last visited longer ago loses its storage at the next save, its cookies staying. Each save replaces the last, so a save after signing out saves you signed out. Every browser opened for this workspace has it back before open_session returns, the one that replaces a reaped browser included. Values are never returned; workspace://site-data lists what is saved.

Parameters

Name	Type	Required	Default
url	string	no	—

Every call names its workspace: an X-Workspace header, or ?workspace=<name>. Sending both is refused. See Workspaces.

Returns

Field	Type	Notes
saved	object	What this save kept, in place of the last. Never a value.
uri	string	workspace://site-data, which lists what is saved.
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.

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.
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.

Example

MCP

save_site_data()

HTTP

curl -X POST $SELENIUM_FLOW/browser/save-site-data \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace: $WORKSPACE"

When to save

Save once a sign-in is confirmed, not before: check the page shows you are in, then call save_site_data. One save keeps every cookie, the localStorage of each site a call has ended on — read in a hidden tab that never loads the site — and the sessionStorage of the page it is on. Each save replaces the last, so a save after signing out saves you signed out.

What restore does

Every browser opened in the workspace has it all back before open_session returns, including the one that replaces a reaped browser: cookies first, then each site's storage, then the page's sessionStorage, then the first page. open_session names the sites in site_data; after a silent reopen, the call that noticed carries that report once. open_session(restore_site_data=false) opens with nothing and deletes what was saved, which is how you start as a new user; where the workspace has been is kept.

Limits

IndexedDB is not saved, and sessionStorage only for the page saved on. Only the sites in the workspace's history are read: a site passed through inside one call is not, and one last visited over a day ago, or beyond the newest 100, loses its saved storage at the next save while its cookies stay. A site whose service worker answers the hidden tab is not read there: it keeps its last saved storage, and a save made while on it reads it directly. An httpOnly cookie cannot be set from a script, so it is restored through the browser's own channel and shown as ••• on every surface. Saved data lives with the workspace's record and expires with it: never on this server's disk, and with the Redis store as durable as Redis. A site that stores what you typed — a token typed through a secret and kept in localStorage — makes it readable in site data; httpOnly cookies stay masked.

---

← All actions · Installing · Deployment