Appearance
Recordings
Recording a room, and the files a recording leaves.
Record a room now
POST /v1/rooms/{sid}/recordings
Records each recorded participant's tracks, one file per track, on the recorder beside the room's media server. Every participant is told before anything is captured, and is told again when the recording stops. Only participants whose clients can show that are recorded; in a room created with recordingRequiresConsent, a participant is recorded only once it has acknowledged the recording.
The room must be sfu, created with a recordingPolicy other than off, and joined by someone: a room nobody has joined has no media yet, and one created with always is recorded from its first join without asking. One recording at a time: a room being recorded is 409 conflict. quota_exhausted when the recordings the application holds have reached maxRecordingGb; recording_unavailable when the deployment does not record rooms, no recorder is running beside the room's media server, or it would not start.
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sid | path | string |
Response 201 — Started; status is starting or active.
| Field | Type | Description |
|---|---|---|
sid | string | Matches ^RC_[0-9a-f]{20}$. |
roomSid | string | Matches ^RM_[0-9a-f]{20}$. |
status | string | starting and active while it records; stopping and processing while its files are finished and uploaded; then complete, or failed — stopped by something other than a request, or never started — with whatever it captured (partial). One of starting, active, stopping, processing, complete, failed. |
layout | string | Every recording is per_track today. One of per_track, composite, audio_only. |
consentRequired | boolean | Participants were recorded only once they acknowledged it. |
partial | boolean | Stopped by something other than a request; its files are what it captured before. |
error | string | null | Why a failed recording stopped — node_failed, egress_restarted, start_failed: … — for a log. |
startedAt | string (date-time) | |
endedAt | string (date-time) | null | |
durationSec | integer | null | |
sizeBytes | integer | null | Written so far while it runs; stored once finished. |
storageKey | string | null | The prefix every file and the timeline are under, once uploaded. |
expiresAt | string (date-time) | null | When retention deletes its files. |
deletedAt | string (date-time) | null | When retention deleted them; the record stays. |
files | RecordingFile[] |
Errors
List recordings, newest first
GET /v1/recordings
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
limit? | query | integer | 1–100. Default 20. |
cursor? | query | string | The nextCursor of the previous page. 1–512 characters. |
roomSid? | query | string | Matches ^RM_[0-9a-f]{20}$. |
status? | query | string | One of starting, active, stopping, processing, complete, failed. |
startedAfter? | query | string (date-time) | Started at or after this instant. |
startedBefore? | query | string (date-time) | Started before this instant. |
Response 200 — A page of recordings.
| Field | Type | Description |
|---|---|---|
data | Recording[] | |
nextCursor | string | null | The cursor for the next page; null on the last. |
Errors
| Status | Code |
|---|---|
| 400 | validation_failed, token_ttl_too_long |
| 401 | unauthenticated, token_expired, token_replayed, token_not_yet_valid |
| 403 | permission_denied, app_suspended, quota_exhausted |
| 429 | rate_limited |
| 500 | internal |
Read one recording, with its files
GET /v1/recordings/{sid}
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sid | path | string |
Response 200 — The recording.
| Field | Type | Description |
|---|---|---|
sid | string | Matches ^RC_[0-9a-f]{20}$. |
roomSid | string | Matches ^RM_[0-9a-f]{20}$. |
status | string | starting and active while it records; stopping and processing while its files are finished and uploaded; then complete, or failed — stopped by something other than a request, or never started — with whatever it captured (partial). One of starting, active, stopping, processing, complete, failed. |
layout | string | Every recording is per_track today. One of per_track, composite, audio_only. |
consentRequired | boolean | Participants were recorded only once they acknowledged it. |
partial | boolean | Stopped by something other than a request; its files are what it captured before. |
error | string | null | Why a failed recording stopped — node_failed, egress_restarted, start_failed: … — for a log. |
startedAt | string (date-time) | |
endedAt | string (date-time) | null | |
durationSec | integer | null | |
sizeBytes | integer | null | Written so far while it runs; stored once finished. |
storageKey | string | null | The prefix every file and the timeline are under, once uploaded. |
expiresAt | string (date-time) | null | When retention deletes its files. |
deletedAt | string (date-time) | null | When retention deleted them; the record stays. |
files | RecordingFile[] |
Errors
Stop a recording
POST /v1/recordings/{sid}/stop
Answered once every file is final; their upload follows, and recording.finished says when it is done. The room's participants are told it stopped. Stopping a recording that has stopped changes nothing and answers the same. A recording also stops when its room ends.
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: write, 120 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sid | path | string |
Response 200 — The recording, as it now stands.
| Field | Type | Description |
|---|---|---|
sid | string | Matches ^RC_[0-9a-f]{20}$. |
roomSid | string | Matches ^RM_[0-9a-f]{20}$. |
status | string | starting and active while it records; stopping and processing while its files are finished and uploaded; then complete, or failed — stopped by something other than a request, or never started — with whatever it captured (partial). One of starting, active, stopping, processing, complete, failed. |
layout | string | Every recording is per_track today. One of per_track, composite, audio_only. |
consentRequired | boolean | Participants were recorded only once they acknowledged it. |
partial | boolean | Stopped by something other than a request; its files are what it captured before. |
error | string | null | Why a failed recording stopped — node_failed, egress_restarted, start_failed: … — for a log. |
startedAt | string (date-time) | |
endedAt | string (date-time) | null | |
durationSec | integer | null | |
sizeBytes | integer | null | Written so far while it runs; stored once finished. |
storageKey | string | null | The prefix every file and the timeline are under, once uploaded. |
expiresAt | string (date-time) | null | When retention deletes its files. |
deletedAt | string (date-time) | null | When retention deleted them; the record stays. |
files | RecordingFile[] |
Errors
Signed URLs for a recording's files
GET /v1/recordings/{sid}/url
Time-limited URLs from which a recording's files and its timeline are fetched straight from the object store; this API never serves the bytes. Anyone holding a URL can fetch the file until it expires. Only a recording that has finished — complete, or failed with what it captured — has files to sign; one still running is 409 conflict, and one whose files retention deleted is 404 not_found.
Credential: API key — Authorization: Bearer <api_key>.<api_secret>
Rate limit: read, 600 a minute
Parameters
| Name | In | Type | Description |
|---|---|---|---|
sid | path | string | |
file? | query | string | One file by its name (TR_….webm, timeline.jsonl); every file when absent. 1–200 characters. |
expiresInSec? | query | integer | How long the URLs work. 60–86400. Default 300. |
Response 200 — The URLs.
| Field | Type | Description |
|---|---|---|
expiresAt | string (date-time) | |
urls | object[] | |
urls[].file | string | |
urls[].url | string (uri) |
Errors