# Pearl REST API check recorder status and download recordings

Recorder status tells you whether a Pearl recorder is running, how long it has been recording, and how many of its sources are active. Recording status is separate from streaming status, which is reported by publishers.

*Applies to: Pearl-2, Pearl Mini, Pearl Nexus, Pearl Nano.*

| Method and path | What it does |
| --- | --- |
| `GET /recorders/status` | Status of every recorder; accepts `ids` to filter |
| `GET /recorders/{rid}/status` | Status of one recorder |
| `GET /recorders/{rid}/archive/files` | Lists recorded files held by that recorder |
| `GET /recorders/{rid}/archive/files/{fid}` | Downloads one recorded file |

**Recorder states** are `disabled`, `starting`, `started`, `stopped`, and `error`. A running recorder also returns `duration` in seconds, plus `active` and `total` source counts. When the state is `error`, a `description` field explains why.

```json
{
  "status": "ok",
  "result": { "state": "started", "duration": 195, "active": "1", "total": "1" }
}
```

**Listing archive files.** The file list accepts `from` (the zero-indexed position of the first file to return) and `limit` (the maximum number of files in the response), so you can page through a long archive. Each file entry reports:

| Field | Meaning |
| --- | --- |
| `id` | File identifier, used in the download path |
| `name` | Display name, such as `HDMI-A_Dec11_17-32-30` |
| `extension` | Media extension, such as `mp4` |
| `recording` | Whether the recording is still in progress |
| `downloaded` | Whether the file has already been downloaded |
| `created` | Creation date and time |
| `duration` | Length in seconds |
| `size` | Size in bytes |
| `recorder` | The recorder that produced it |
| `uploading` | Whether an upload of this file is in progress |
| `event_id` | The scheduled event this file belongs to, if any |

**Downloading.** The download endpoint returns the raw media as `application/octet-stream`. Pass the `id` value from the file list as `{fid}`. A missing recorder or a missing file both return 404.

> product: pearl-family · topic: recording · source: pearl-rest-api.md · updated: Oct 7, 2026