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

# Recording playback readiness

> stub — Understand whether a listed recording is ready to play.

Each recording returned by `GET /api/v1/environments/{uuid}/recordings` includes
an optional `playback_readiness` object. Its top-level `state` tells you whether
the recording is `ready`, `materializing`, or `failed`; its `streams` list gives
the same detail for each available camera, robot, audio, depth, or point-cloud
stream.

## HTTP API defaults

`GET /api/v1/environments/{uuid}/recordings` and
`GET /api/v1/environments/{uuid}/recordings/availability` share the same
filters, but their defaults are intentionally different from Python
`recordings.list()`:

| Request                    | No date range                                   | Pagination                                                            | Readiness default                                                                                                                                      |
| -------------------------- | ----------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/recordings`              | Searches the whole eligible environment history | First 100 newest items (`limit` defaults to 100 and is capped at 100) | Non-admin users get ready rows only. Staff/admin users follow the deployment policy; pass `include_unready=false` for a predictable ready-only result. |
| `/recordings/availability` | Reports all eligible dates in the environment   | Not paginated                                                         | Same readiness rules as `/recordings`; `timezone` defaults to `UTC`.                                                                                   |

To apply a date window, send **both** `start_date` and `end_date` (or both
legacy `start_timestamp` and `end_timestamp` aliases). A one-sided date query
does not produce a date-window filter. Repeated `twin_uuid`, `context`, and
`source_type` values are ORed within each kind and ANDed across kinds.

## Include recordings that are not ready

Pass `include_unready=false` for ready recordings only. Pass
`include_unready=true` to include recordings that are still materializing or
have failed; that value requires staff/administrator access:

```text theme={null}
GET /api/v1/environments/{uuid}/recordings?include_unready=true
```

## Browse a large catalog or populate a calendar

Pass `limit` to receive a stable page ordered newest-first. Follow the opaque
`next_cursor` while `has_more` is true; cursors are signed and bound to the
current filters, so a `400 Invalid recording catalog cursor` means restart the
query. `limit` is capped at 100.

```text theme={null}
GET /api/v1/environments/{uuid}/recordings?limit=50&source_type=camera&include_unready=false
```

You can repeat `twin_uuid`, `context`, or `source_type`; values are ORed within
the same filter and combined with other filters. Source values are `camera`,
`robot`, `audio`, `depth`, and `pointcloud`. Responses include source, twin,
context, and readiness facets for the fully filtered catalog.

For calendar day counts without loading media, request availability with the
same filters. Use an IANA timezone when the calendar is not UTC.

```text theme={null}
GET /api/v1/environments/{uuid}/recordings/availability?start_date=2026-08-01&end_date=2026-08-31&timezone=Europe/Rome
```

Availability does not sign media URLs or probe object storage.

## Retry materializing playback

`GET /api/v1/environments/{uuid}/recordings/{recording_uuid}/data` can return
`202 Accepted` when the recording is known but its playback files are not ready
yet. The response includes `retry_after_seconds`; wait approximately that long
and retry the same request instead of treating it as a missing recording.