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

# Recordings

> Every screen the agent looked at, kept so you can replay a task.

The agent works from screenshots: it looks at the screen, acts, and looks again. GuidingHand keeps each of those screenshots as a **frame**, so every task can be replayed afterwards exactly as the agent saw it. Nothing extra is captured: a recording is only the screens the agent already looked at while the task ran, not a video of the customer's day.

## Replay in the console

Every task has a `replay_url`, such as `https://guidinghand.ai/console/acme/tasks/task_mW8mcFPUN7Of`. It opens the task in the console: the recorded screens with the agent's pointer and clicks drawn on them, next to the timeline of events, questions, approvals and the result. Anyone in the org can open it after signing in. Put the link in your ticket so whoever reads the ticket later can see what happened.

## Frames through the API

`GET /v1/tasks/{task_id}/recording` lists the frames in order:

```json theme={null}
{
  "object": "recording",
  "task_id": "task_mW8mcFPUN7Of",
  "frames": [
    { "seq": 1, "t_ms": 1840, "after_event": 2, "width": 1470, "height": 956,
      "url": "https://guidinghand.ai/v1/tasks/task_mW8mcFPUN7Of/recording/1" },
    { "seq": 2, "t_ms": 5120, "after_event": 3, "width": 1470, "height": 956,
      "url": "https://guidinghand.ai/v1/tasks/task_mW8mcFPUN7Of/recording/2" }
  ]
}
```

| Field             | Meaning                                                                                  |
| ----------------- | ---------------------------------------------------------------------------------------- |
| `seq`             | The frame's number, from 1.                                                              |
| `t_ms`            | Milliseconds from the start of the task.                                                 |
| `after_event`     | The `cursor` of the last event before this screen. Use it to line frames up with events. |
| `width`, `height` | The screen's size in pixels.                                                             |
| `url`             | The frame as a PNG.                                                                      |

Frame URLs need your API key like every other `/v1` request, so fetch them from your server rather than putting them in an `<img>` tag:

```bash theme={null}
curl https://guidinghand.ai/v1/tasks/task_mW8mcFPUN7Of/recording/1 \
  -H "Authorization: Bearer $GUIDINGHAND_API_KEY" \
  -o frame-1.png
```

`GET /v1/tasks/{task_id}` also returns `recording.frames`, the number of frames.

## Retention

Two org settings control how long things are kept. Admins change them in the console under **Settings → Recording and retention**.

| Setting        | Default | What it covers                   |
| -------------- | ------- | -------------------------------- |
| `frame_days`   | 30 days | Recorded screens.                |
| `history_days` | 90 days | Tasks, their events and results. |

Each can be 1 to 3,650 days. Older data is deleted automatically. Once a task's frames have expired, its recording is empty but the task and its events stay until `history_days`.

## Turning recording off

An org can turn recording off in the same place. New tasks then keep no frames; recordings already saved stay until they expire. The agent still takes screenshots to do its work; they just aren't kept.

## Deleting

`DELETE /v1/sessions/{session_id}` deletes the session's tasks, events and recordings for good, including their replays. Use it when a customer asks you to remove their data. It needs the admin role or an API key, and it is recorded in the org's [audit log](/concepts/orgs#audit-log).