> For the complete documentation index, see [llms.txt](https://zumo.fusion.ac/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zumo.fusion.ac/documentation/guides/recording-a-replay.md).

# Recording a replay

Always check HTTP before emitting `replayRequest`. Use WebSocket for live progress and completion.

{% stepper %}
{% step %}

## Check HTTP first

```js
const headers = { 'API-Key': KEY };
const check = await fetch(`${HUB_URL}/replays/${replayId}`, { headers });
```

| Status        | Next step                               |
| ------------- | --------------------------------------- |
| `200`         | Already done; use body + MCPR URL       |
| `404`         | Emit `replayRequest`                    |
| `425`         | Poll `/status` or listen on WS          |
| `422`         | Emit `replayRequest` with `force: true` |
| {% endstep %} |                                         |

{% step %}

## Emit replayRequest

Requires `replayRequest` on the key’s **provide** ACL. Do not filter the socket with `mode: 'replay'` if you need `replayFinished`.

```js
const socket = io(HUB_URL, { auth: { key: KEY } });

socket.on('connect', () => {
  socket.emit('replayRequest', {
    replayId,
    force: check.status === 422,
  });
});
```

{% endstep %}

{% step %}

## Handle lifecycle

```js
socket.on('replayFinished', async (data) => {
  if (data.replayId !== replayId) return;
  const res = await fetch(`${HUB_URL}/replays/${replayId}`, { headers });
  console.log((await res.json()).result);
  // MCPR: `${HUB_URL}/replays/${replayId}/mcpr` (public)
});

socket.on('replayRejected', console.error);
socket.on('replayFailed', console.error);
```

{% endstep %}
{% endstepper %}

## IDs

`replayId` must match `/^[0-9a-f-]{32,36}$/i` (normalized lowercase). Each id is recorded successfully at most once unless you force.

See [Errors and retries](/documentation/guides/errors-and-retries.md) and [HTTP GET /replays/{replayId}](https://app.gitbook.com/s/M9ty6FYa3j98VSBHF9LN/http/get-replay).