---
title: "Start Recording Episode"
method: POST
path: "/recording/start"
tags: ["recording"]
---

# Start Recording Episode

`POST /recording/start`

## Request

- The document declares no server URL.
- Auth: none required

Asynchronously start recording an episode in the background.
Output format is chosen when stopping the recording.

## Request body

- RecordingStartRequest: Request to start the recording of an episode.
  - `add_metadata` object, nullable: Passing a dictionnary will store the value in each row of the recorded dataset. The key is the name of the column, and the value is a list. If set to None, no additional metadata is saved.
  - `branch_path` string, nullable: Path to the branch to push the dataset to, in addition to the main branch. If set to None, only push to the main branch. Defaults to None.
  - `cameras_ids_to_record` integer[], nullable: List of camera ids to record. If set to None, records all available cameras.
  - `dataset_name` string, nullable: Name of the dataset to save the episode in.If None, defaults to the value set in Admin Configuration.
  - `enable_rerun_visualization` boolean: Enable rerun
  - `episode_format` 'json' | 'lerobot_v2' | 'lerobot_v2.1', nullable: Format to save the episode. `json` is compatible with OpenVLA and stores videos as a series of npy. `lerobot_v2` is compatible with [lerobot training.](https://docs.phospho.ai/learn/ai-models).If None, defaults to the value set in Admin Configuration.
  - `freq` integer, nullable: Records steps of the robot at this frequency.If None, defaults to the value set in Admin Configuration.
  - `instruction` string, nullable: A text describing the recorded task. If set to None, defaults to the value set in Admin Configuration.
  - `leader_arm_ids` string[], nullable: Serial numbers of the leader arms used during the recording
  - `robot_serials_to_ignore` string[], nullable: List of robot serial ids to ignore. If set to None, records all available robots.
  - `save_cartesian` boolean: Record cartesian positions of the robots as well, this will make your dataset incompatible with lerobot and it only works for robots with simulators. Defaults to False.
  - `target_video_size` unknown[], nullable: Target video size for the recording, all videos in the dataset should have the same size. If set to None, defaults to the value set in Admin Configuration.
    - unknown
  - `video_codec` 'avc1' | 'hev1' | 'mp4v' | 'hvc1' | 'avc3' | 'av01' | 'vp09' | 'av1', nullable: Codec to use for the video saving.If None, defaults to the value set in Admin Configuration.

## Response `200`

Successful Response

- StatusResponse: Default response. May contain other fields.
  - `message` string, nullable
  - `status` 'ok' | 'error'

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/phospho/apis/phospho-api.md) - [All operations](https://skmtc.dev/phospho/apis/phospho-api/llms.txt) - [OpenAPI document](https://skmtc.dev/phospho/apis/phospho-api/revisions/93e83588fc02?raw)