> ## Documentation Index
> Fetch the complete documentation index at: https://offstage.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To set up offstage cloud from a coding agent, read https://api.offstage.cloud/SKILL.md and follow it. The whole API guide is one file at https://api.offstage.cloud/llms.txt.

# Recordings

> Every GUI sandbox and task leaves a replay: its screen, commands and agent steps.

GUI recording APIs require a GUI sandbox or task.

A `gui` sandbox and a `gui` task leave a recording: the slot's screen from start to end, with what happened in between. It plays back after the sandbox closes or the task ends, when the slot has already been wiped. Create one with `"record": false` to keep none. A `headless` sandbox or task has no screen and records nothing. Recording costs nothing.

* **Pictures.** A sandbox is pictured once it is `ready`, about a second after each command, and every 4 s while an agent run goes. A task is pictured every 5 s while it runs. These are JPEGs at most 960 pixels on the long side (PNGs from a Mac that cannot make a JPEG). An agent run's own screenshots are kept too, as PNGs the size the model saw.
* **Entries.** Each command (its line, cut at 2,000 characters, its exit code, its duration and the last 8 KiB of its output; never its `envs`), each agent run's start, steps and end, a task's log lines, and the end with its reason.
* **Quiet.** The plane's own pictures are not ops: they do not count in `ops`, do not keep an idle sandbox open, and are skipped while your ops wait for a place.
* **Private.** Only your team can read it, with a key or in the console. `replayUrl` on the sandbox, the task or the agent run is the console page that shows it live and plays it back, behind the console's sign-in. That page also exports the replay as a GIF or a video.
* **Kept** 7 days after its last picture or entry, as artifacts are. It holds at most 3,000 pictures, 128 MiB of them and 10,000 entries; past any of those `truncated` is true, and it stops keeping more but still records its end.

| Call | Answer |
| - | - |
| `GET /v1/recordings/:id` | The recording; `:id` is the sandbox's or the task's id. 404 `recording-not-found` when there is none |
| `GET /v1/recordings/:id/frames/:frame` | One picture an entry names, as `image/jpeg` or `image/png` |
| `GET /v1/recordings/:id/live?after=<seq>` | A server-sent event stream: an `entry` event (its `id` is the entry's `seq`) for each entry after `after`, then each new one as it happens, then one `end` event with the recording's summary. A stream lasts at most 10 minutes; reconnect with `Last-Event-ID`, or `after`, set to the last `seq` you have |

```json theme={null}
{
  "id": "sbx_…",
  "kind": "sandbox",
  "name": "swift-otter",
  "state": "ended",
  "startedAt": 1793000000000,
  "endedAt": 1793000300000,
  "frames": 41,
  "truncated": false,
  "replayUrl": "https://…/r/sbx_…",
  "entries": [
    { "seq": 1, "at": 1793000001600, "type": "frame", "frame": "frame-0001.jpg", "width": 960, "height": 600, "source": "start" },
    { "seq": 2, "at": 1793000012000, "type": "command", "command": "open -a TextEdit", "exitCode": 0, "timedOut": false, "durationMs": 310, "output": "", "truncated": false },
    { "seq": 4, "at": 1793000020000, "type": "run", "runId": "run_…", "event": "started", "goal": "…", "model": "claude-opus-5-5" },
    { "seq": 5, "at": 1793000021000, "type": "step", "runId": "run_…", "action": "left_click", "input": { "coordinate": [640, 320] }, "ok": true, "space": { "width": 1280, "height": 800 } },
    { "seq": 41, "at": 1793000300000, "type": "end", "reason": "deleted" }
  ]
}
```

* `state` is `recording` while the sandbox or task is open, then `ended`.
* `type` is `frame` (a picture; `source` is `start`, `command`, `background` or `task`), `command`, `input` (a call to [Click, type and press keys](https://offstage.cloud/docs/api/sandboxes.md#click-type-and-press-keys): `actions`, one line each, `performed`, and `error` if it failed), `run` (`event` `started` with the goal and model, or `finished` with the verdict), `step` (an agent run's step as in [Hand the screen a goal](https://offstage.cloud/docs/api/sandboxes.md#hand-the-screen-a-goal); a screenshot step's `frame` is one of the recording's pictures), `log` (a task's `lines`) or `end`.
* A step's coordinates are pixels of the picture the model saw, whose size is its `space`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.