---
title: "List clips for a video"
method: GET
path: "/v1/videos/{id}/clips"
tags: ["Clips"]
---

# List clips for a video

`GET /v1/videos/{id}/clips`

Returns the clips of a video in playback order.

## Path parameters

- `id` string, required — Video identifier

## Response `200`

OK

- ListClipsResponse — Response shape for listing clips of a video
  - `clips` Clip[], required — Clips in the video, ordered by `order`
    - `animatedCursor` boolean — Whether the clip draws an animated cursor from captured mouse data. Absent when the clip has no screen recording.
    - `background` ClipBackgroundOutput, required — Clip background. Use type = 'solid' with `color`, type = 'image' or 'video' with `sourceId` (from `POST /v1/sources`) or an exact catalog URL from `GET /v1/backgrounds`, or type = 'gradient' with `gradientColor1`, `gradientColor2`, `gradientAngle`.
      - `color` string, nullable — Hex color string. Required when type = 'solid'.
      - `gradientAngle` integer, nullable — Linear gradient angle in degrees. Required when type = 'gradient'.
      - `gradientColor1` string, nullable — Hex color string. Required when type = 'gradient'.
      - `gradientColor2` string, nullable — Hex color string. Required when type = 'gradient'.
      - `imageUrl` string, uri, nullable — Hosted image URL. Present in responses and accepted as input only when copied exactly from `GET /v1/backgrounds`; otherwise pass `sourceId`.
      - `sourceId` string, nullable — Source ID from `POST /v1/sources` (`kind: image` for type = 'image', `kind: video` for type = 'video'). Required for image/video backgrounds unless using an exact URL from `GET /v1/backgrounds`. Input-only.
      - `type` 'solid' | 'gradient' | 'image' | 'video', required — Background variant
      - `videoDurationSeconds` number, nullable — Video background duration in seconds. Read-only: derived from the uploaded source or catalog entry on input.
      - `videoUrl` string, uri, nullable — Hosted video URL. Present in responses and accepted as input only when copied exactly from `GET /v1/backgrounds`; otherwise pass `sourceId`.
    - `createdAt` string, date-time, required — ISO 8601 datetime
    - `cuts` CutOutput[], required — Time ranges cut from the clip's playback
      - `durationMs` integer, required — Length of the cut, in milliseconds
      - `startTimeMs` integer, required — Start of the cut, in ms of the raw recording
    - `durationSeconds` number, required — Effective playback duration of the clip after cuts, in seconds
    - `id` string, required — Unique clip identifier
    - `layoutSceneType` 'basicSubject' | 'cameraSubject' | 'combi', required — How a clip composes its layers, which determines the set of layouts it accepts: `basicSubject` (screen-only), `cameraSubject` (camera-only), or `combi` (camera + presentation).
    - `maxDurationSeconds` number, required — Total length of the underlying source, in seconds
    - `microphoneVolume` number, nullable — This clip's microphone volume override: a number when the clip overrides the video's `microphoneVolume`, null when it follows it, and absent when the clip has no microphone audio to control — either no such track, or a track whose recording carries no audio (a muted mic, or a screen recording made without sharing system audio).
    - `name` string, required — Clip display name
    - `order` integer, required — Position of the clip within the video
    - `studioSound` boolean, required — Effective Studio Sound (AI audio enhancement) state for this clip: the video-level switch minus this clip's opt-out.
    - `systemAudioVolume` number, nullable — This clip's system audio (screen or uploaded footage) volume override, with the same three states as `microphoneVolume`.
    - `transition` 'default' | 'smooth' | 'hard_cut', required — How a clip enters from the previous one. `default` inherits the video's `defaultClipTransition`; `smooth` and `hard_cut` override it for this clip. The first clip in a video has nothing to transition from.
    - `updatedAt` string, date-time, required — ISO 8601 datetime
    - `videoId` string, required — Video identifier

## Other responses

- `400` — The request was malformed or contained invalid parameters.
- `401` — Authentication is required. Provide a valid API key.
- `403` — You don't have permission to access this resource.
- `404` — The requested resource was not found.
- `429` — You have exceeded the rate limit. Please slow down.
- `500` — An unexpected error occurred
- `501` — The requested operation is not implemented.

---

[API](https://skmtc.dev/withchima/apis/tella-public-api.md) · [All operations](https://skmtc.dev/withchima/apis/tella-public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/withchima/tella-public-api/revisions/cd69045c703a/schema)