---
site: steel.dev
collection: docs
canonical_url: https://steel.dev/docs/control/snapshots-and-refs
markdown_url: https://steel.dev/docs/control/snapshots-and-refs.md
content_signal: ai-input=yes, ai-train=yes, search=yes
title: Snapshots and refs
description: "Commands, the MCP server, and the CLI share one model: take a snapshot of the page, pick an element by its ref, and act on it."
summary: "Commands, the MCP server, and the CLI share one model: take a snapshot of the page, pick an element by its ref, and act on it."
type: concept
reviewed: 2026-11-12
prerequisites:
  - https://steel.dev/docs/control.md
related:
  - https://steel.dev/docs/control.md
  - https://steel.dev/docs/control/cli.md
  - https://steel.dev/docs/control/skills.md
  - https://steel.dev/docs/control/mcp-server.md
  - https://steel.dev/docs/control/cdp.md
agent_setup: https://setup.steel.dev/install.md
docs_index: https://steel.dev/docs/sitemap.md
---

# Snapshots and refs

A snapshot is a text version of a page that a language model can read. It lists the page's elements. Each element that you can act on or point to, such as a link, a field or a heading, gets a short name: its ref. The model reads the snapshot, picks a ref, and sends it back in a command such as `click`. [Commands](https://steel.dev/docs/control/commands), the [MCP server](https://steel.dev/docs/control/mcp-server) and the [Steel CLI](https://steel.dev/docs/control/cli) all work this way. Some names differ, such as `press_key` in the MCP server for the `press` command. [Names in the CLI and the MCP server](https://steel.dev/docs/reference/commands#names-in-the-cli-and-the-mcp-server) maps them.

A screenshot shows pixels, and a page's HTML holds far more than a model needs. A snapshot keeps what a person would use: the headings, links, fields and buttons, with their names and states.

## Snapshots

A snapshot is the page's accessibility tree, as text. Each line is one element: its role, its name in quotes, its states in brackets, and its ref. A field's value follows the colon. Plain text, such as a paragraph, has no ref.

```text nocopy
- heading "Account" [level=1, ref=e1]
- textbox "Name" [ref=e2]: Ada
- checkbox "Remember me" [checked=false, ref=e3]
- button "Save" [ref=e4]
- generic "Open card" [ref=e5] clickable [cursor:pointer]
```

These options make a snapshot shorter:

| Option | The snapshot keeps |
| - | - |
| `interactive` | Only the lines with refs. This fits most agent steps. |
| `compact` | The lines with refs or values, and their ancestors. |
| `depth` | The lines up to this depth. |

Each snapshot has a `snapshotId`. After an action, a request can ask for a new snapshot, or for a diff against the tab's last snapshot. A diff lists only the lines that changed, so the model reads less after each step.

A password field shows as `••••••••` in a snapshot, and in the text that other commands return. A [`get`](https://steel.dev/docs/reference/commands#get) of its value leaves the value out and sets `masked` to `true`. Any field that shows dots instead of its text is masked the same way. When Steel fills a sign-in form with a [credential](https://steel.dev/docs/logins/credentials), it shows dots in the username field too, so a snapshot masks the username as well. When the session sets the credentials option [`blurFields`](https://steel.dev/docs/sessions/configuration#credentials) to `false`, the username shows as it is.

## Refs

A ref, such as `e12`, names one element on one page. It stays the same across snapshots of that page, so a model can act on a ref from an older snapshot while the element is still there.

A ref goes stale when its element leaves the page, or when the page reuses the element for other content, as a list can. A command on a stale ref fails with `stale_ref`. Take a new snapshot, and pick the element again.

A ref is valid only in its session. To find the same element in a later session, use a locator: its role and name, its label, its text, or a CSS selector. The `get` command with `what` set to `locator` returns locators for an element, best first. A command accepts a ref, a CSS selector or a locator as its `target`.

In a snapshot, a ref shows as `ref=e12`. Pass it to a command as `e12` or as `ref=e12`.

A ref also knows its tab, so a command on a ref acts on that tab and needs no `tab` field. [Tabs](https://steel.dev/docs/reference/commands#tabs) in the Commands reference explains how other commands pick a tab, and how to answer a JavaScript dialog that blocks one.

## Page state and `after`

Every response with status `200` has a `next` value. Send it as `after` in your next request. It tells Steel which state of the session you last saw.

When you retry with the same `after` and the same commands, Steel does not run the commands again. The retry returns the stored result.

When the session has changed since that `next`, the response sets `epochChanged` to `true`. Another execution that changed the page, or a browser restart, counts as a change. Input from a CDP client or from the live view does not count.

When something else has changed the page, take a new snapshot before you act on old refs. If Steel no longer knows your `after`, the request fails with `invalid_operation_token`, and the response carries a fresh `next`. Check the page before you send the commands again, because they may have run.

## Executions

Each request runs as one execution, with an ID such as `x-1`. Its commands run in order and stop at the first failure. Steel does not undo the commands that already ran.

[Executions](https://steel.dev/docs/reference/commands#executions) in the Commands reference has an execution's states, how long a response waits for it, and the rules for a safe retry.
