Recordings

A recording captures the phone's screen as a video, so you can watch what an agent did, share a failing run, or make a demo. It captures everything on the screen, passwords and codes included, so treat its video like the phone's own data.

• One recording runs at a time on each phone. Starting and stopping one needs a ready phone; listing, downloading and deleting work in any status.
• A project keeps at most 20 recordings. Phonebox deletes each one 7 days after it started, and expires_at says when.
• A recording is recording until you stop it, then processing until its video is ready, then ready. One that couldn't be saved is failed.
• Starting, stopping and deleting are sent to the phone once and never retried. Recording is included in the phone's running time: it costs nothing extra.
• Some phones can't record. Starting a recording on one fails with 422 feature_unavailable, with details.feature set to recordings.

Start a recordingCopy Anchor Link

POST /v1/phones/{id}/recordings needs the phones:control scope.

{
  "name": "checkout flow"
}

curl -X POST https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta/recordings \
  -H "Authorization: Bearer $PHONEBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "checkout flow"}'

It answers 201 Created with the recording.

{
  "object": "recording",
  "id": "rec_q3m7x2k6v4tb",
  "phone": "ph_7kx2m6q4v3ta",
  "name": "checkout flow",
  "status": "recording",
  "started_at": "2026-09-30T10:00:00.000Z",
  "ended_at": null,
  "duration_ms": null,
  "size_bytes": null,
  "expires_at": "2026-10-07T10:00:00.000Z"
}

List recordingsCopy Anchor Link

GET /v1/phones/{id}/recordings needs the phones:read scope.

The phone's recordings, newest first.

curl https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta/recordings \
  -H "Authorization: Bearer $PHONEBOX_API_KEY"

{
  "data": [
    {
      "object": "recording",
      "id": "rec_q3m7x2k6v4tb",
      "phone": "ph_7kx2m6q4v3ta",
      "name": "checkout flow",
      "status": "ready",
      "started_at": "2026-09-30T10:00:00.000Z",
      "ended_at": "2026-09-30T10:02:14.000Z",
      "duration_ms": 134000,
      "size_bytes": 18350080,
      "expires_at": "2026-10-07T10:00:00.000Z"
    }
  ]
}

Stop a recordingCopy Anchor Link

POST /v1/phones/{id}/recordings/{rid}/stop needs the phones:control scope.

Stops the recording and answers with it, now processing or already ready. Stopping one that has already stopped answers with it as it is, and sends nothing to the phone.

curl -X POST https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta/recordings/rec_q3m7x2k6v4tb/stop \
  -H "Authorization: Bearer $PHONEBOX_API_KEY"

Download a recordingCopy Anchor Link

GET /v1/phones/{id}/recordings/{rid}/video needs the phones:read scope.

The video, as an MP4 file named after the recording's ID. It streams from Phonebox itself.

curl -o checkout.mp4 https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta/recordings/rec_q3m7x2k6v4tb/video \
  -H "Authorization: Bearer $PHONEBOX_API_KEY"

Delete a recordingCopy Anchor Link

DELETE /v1/phones/{id}/recordings/{rid} needs the phones:control scope.

Deletes the recording and its video. This can't be undone. A recording that is still running is stopped first.

curl -X DELETE https://phonebox.dev/v1/phones/ph_7kx2m6q4v3ta/recordings/rec_q3m7x2k6v4tb \
  -H "Authorization: Bearer $PHONEBOX_API_KEY"

{
  "id": "rec_q3m7x2k6v4tb",
  "deleted": true
}