---
title: "Record the desktop to an MP4 file."
method: POST
path: "/v1/sandboxes/{id}/desktop/recordings"
tags: ["desktop"]
---

# Record the desktop to an MP4 file.

`POST /v1/sandboxes/{id}/desktop/recordings`

## Request

- Base URL: `https://api.withruntime.com`
- URL: `https://api.withruntime.com/v1/sandboxes/{id}/desktop/recordings`
- Auth: HTTP bearer

Starts recording the running desktop and answers once frames are being written. One recording at a time. The recorder uses one encoder thread at low priority, at most 30 fps; the file never exceeds maxMiB and recording stops while the sandbox's disk still has 256 MiB free. The file is on the sandbox's own disk and counts toward it; a sandbox keeps at most 8192 MiB of recordings. It is a fragmented MP4, so a recording cut short still plays. The first recording in a sandbox without ffmpeg installs it (up to a minute). Needs exec. 507 insufficient_storage when there is no room.

## Path parameters

- `id` string, required: Resource identifier (UUID).

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `fps` integer: Frames a second. Default 10.
  - `maxSeconds` integer: Stop after this much video. Default 1800.
  - `maxMiB` integer: The file never grows past this. Default 512.
  - `crf` integer: Quality: 18 is sharp and large, 45 small. Default 30.

## Response `200`

Success

- object
  - `id` string, required
  - `state` 'starting' | 'installing' | 'recording' | 'finished' | 'failed', required
  - `path` string, required: The MP4 file in the sandbox.
  - `bytes` integer, required
  - `seconds` number
  - `reason` string, nullable: Why it ended: stopped, max-seconds, max-bytes, disk-low (the disk reached its 256 MiB reserve), desktop-gone, error.
  - `processId` string, nullable
  - `startedAt` integer, nullable

## Other responses

- `default`: Error

---

[API](https://skmtc.dev/withruntime/apis/runtime-cloud-api.md) · [All operations](https://skmtc.dev/withruntime/apis/runtime-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/withruntime/apis/runtime-cloud-api/revisions/6f4012286988?raw)