---
title: "Start a recording"
method: POST
path: "/v1/recordings"
tags: ["AI Recorder"]
---

# Start a recording

`POST /v1/recordings`

## Request

- Base URL: `https://api.vidocu.ai`
- URL: `https://api.vidocu.ai/v1/recordings`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://vidocu.ai/oauth/authorize`, token URL `https://api.vidocu.ai/oauth/token`)

Describe a flow and the agent records it. Long-running — poll the job. Billed per minute of finished video; failed and aborted jobs are free. On a site with a saved login, pass sessionId to pick one; omit it to use the site's default session.

**Scope:** `recordings:write`

**Role permission:** `canCreate` (OAuth only — API keys carry full workspace permissions)

## Request body

- object
  - `prompt` string, required: What the recording should show, up to 50,000 characters
  - `url` string, uri
  - `device` 'desktop' | 'mobile'
  - `pacing` 'relaxed' | 'standard' | 'brisk'
  - `maxDurationSec` number: Max finished-video length in seconds; 0 or absent = no limit
  - `removeLoading` boolean: Cut page-load waits (the first load, navigations, loads after a click) out of the video. Default false
  - `mode` 'regular' | 'follow' | 'steps'
  - `steps` object[]
    - `instruction` string, required
    - `url` string, uri
  - `sessionId` string: The saved login to start signed in with, by id from GET /v1/recorder-sessions. A site can have several (e.g. "Sandbox" and "Admin user"). Omit it to use the site's default session.

## Response `202`

Recording started

## Other responses

- `400`: Validation error
- `401`: Invalid or missing credentials
- `403`: Missing scope (`insufficient_scope`), insufficient role (`insufficient_role`), or quota exhausted (`limit_exceeded`)
- `422`: The recorder judged the prompt not actionable
- `429`: Rate limit exceeded (60 req/min)
- `500`: Server error

---

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