# Recordings

> One MP4 of the top quality, a few minutes after the stream ends. Download it, keep it as long as you like, or delete it.

Unless you create a stream with `"record": false`, JustOnAir keeps what is streamed and turns it into **one MP4 of the top quality** after the stream ends. Other sizes are not kept; make them from the MP4 if you need them.

There is no replay through the player or `playback_url`. An ended stream is ended; the MP4 is how you keep it.

## Status

`recording` on the stream tells you where it is:

| `recording.status` | Meaning |
|---|---|
| `recording` | The stream is live and being kept. |
| `processing` | The stream has ended and the MP4 is being made. Usually a few minutes. |
| `ready` | Download it. `bytes`, `duration_seconds` and `delete_at` are set. |
| `not_recorded` | Created with `record: false`. |
| `none` | The stream never went live. |
| `deleting`, `deleted` | You asked for it to be deleted, or it reached `delete_at`. |
| `failed` | The MP4 could not be made after three tries. What was streamed is kept, so it can be made again. |

## Download

```bash
curl https://api.justonair.com/v1/streams/str_e1bzk3dxw9z9allei6n7/recording/download \
  -H "Authorization: Bearer $JOA_API_KEY" -H "Content-Type: application/json" \
  -d '{"expires_in": 3600}'
```

```json
{
  "object": "recording_download",
  "stream_id": "str_e1bzk3dxw9z9allei6n7",
  "url": "https://live.joacdn.com/bcdn_token=.../_rec/str_e1bzk3dxw9z9allei6n7/recording.mp4",
  "bytes": 231486012,
  "expires_at": "2026-09-29T12:21:04.000Z"
}
```

The link works for `expires_in` seconds (60 to 7 days, default 1 hour) and supports range requests, so download tools can resume. Downloading counts as delivery at the normal per-GB rate.

To feed a video library, wait for the [`recording.ready` webhook](/webhooks) (or poll the stream until `recording.status` is `ready`), then fetch the link and copy the file.

## How long it is kept

30 days by default, then deleted. Change it per stream when you create it:

| `recording_retention_days` | Kept |
|---|---|
| omitted | Your account default (30 days) |
| `1` to `3650` | That many days after it is ready |
| `null` | Until you delete it |

`recording.delete_at` always shows the actual date.

> **Warning:** If your credit balance stays at zero or below for 7 days, your recordings are deleted. `delete_at` and `delete_reason: "zero_balance"` show the deadline from the first day; topping up stops it.

## Delete

```bash
curl -X DELETE https://api.justonair.com/v1/streams/str_e1bzk3dxw9z9allei6n7/recording \
  -H "Authorization: Bearer $JOA_API_KEY"
```

Deletes the MP4 now, or as soon as it is made if it is still processing.

## Price

$0.03 per GB per month, counted by the hour. A one-hour 720p recording is about 1.1 GB: $0.034 a month.