Videos

Get a video's timeline

Returns a compact ordered timeline outline by default: video identity, version, dimensions and duration plus every clip's video-timeline start, playback duration and content counts. Use include to fetch specific video or clip details, optionally scoped by clipIds; the complete outline remains in every response. Use include=all for the complete edit state. Effect and word times are ms on each clip's playback timeline (cuts applied). Raw cuts retain the source-recording timing used by the clip endpoints.

get/v1/videos/{id}/timeline

Path parameters

idstring required

Unique video identifier

Example:vid_abc123def456

Unique video identifier

Query parameters

clipIdsstring

Comma-separated clip IDs to return details for. The complete ordered clip outline is always returned.

Example:scn_abc123,scn_def456

Comma-separated clip IDs to return details for. The complete ordered clip outline is always returned.

includestring

Comma-separated details to include: all, settings, chapters, backgroundMusic, clipSettings, cuts, layouts, zooms, blurs, highlights, overlays, textOverlays, soundEffects, transcript, words. Default: none.

Example:layouts,zooms,words

Response

The video's edit state

includedstring[] required

Detail categories included in this response

Example response

{
  "details": {
    "clips": [
      {
        "background": {
          "color": "#000000ff",
          "gradientAngle": 45,
          "gradientColor1": "#ff0080ff",
          "gradientColor2": "#7928caff",
          "sourceId": "su_abc123",
          "type": "solid",
          "videoDurationSeconds": 12.4
        },
        "blurs": [
          {
            "dimensions": {
              "heightPct": 50,
              "widthPct": 50
            },
            "durationMs": 2000,
            "id": "ly_abc123",
            "point": {
              "xPct": 25,
              "yPct": 25
            },
            "startTimeMs": 1000,
            "type": "blur"
          }
        ],
        "cuts": [
          {
            "durationMs": 750,
            "startTimeMs": 1500
          }
        ],
        "highlights": [
          {
            "dimensions": {
              "heightPct": 50,
              "widthPct": 50
            },
            "durationMs": 2000,
            "id": "ly_abc123",
            "point": {
              "xPct": 25,
              "yPct": 25
            },
            "startTimeMs": 1000,
            "type": "blur"
          }
        ],
        "layoutSceneType": "combi",
        "layouts": [
          {
            "durationMs": 5000
          }
        ],
        "overlays": [
          {
            "dimensions": {
              "height": 540,
              "width": 960
            },
            "durationMs": 5000,
            "id": "ly_abc123",
            "name": "Logo",
            "point": {
              "xPct": 30,
              "yPct": 30
            },
            "sourceId": "su_abc123",
            "startTimeMs": 1000,
            "transition": "smooth",
            "type": "image"
          }
        ],
        "soundEffects": [
          {
            "durationMs": 3000,
            "id": "ly_abc123",
            "name": "Whoosh",
            "sourceId": "su_abc123",
            "startTimeMs": 1000,
            "volume": 1
          }
        ],
        "textOverlays": [
          {
            "background": {
              "color": "#5E51F8FF",
              "type": "solid"
            },
            "backgroundShape": "squircle",
            "color": "#FFFFFFFF",
            "dimensions": {
              "height": 540,
              "width": 960
            },
            "durationMs": 5000,
            "fontFamily": "Inter",
            "fontSize": 81,
            "fontWeight": 500,
            "fontWidth": 100,
            "id": "ly_abc123",
            "point": {
              "xPct": 30,
              "yPct": 30
            },
            "startTimeMs": 1000,
            "text": "Welcome back",
            "textAlign": "center",
            "transition": "smooth"
          }
        ],
        "words": [
          {
            "endTimeMs": 1800,
            "index": 12,
            "startTimeMs": 1500,
            "text": "Hello"
          }
        ],
        "zooms": [
          {
            "durationMs": 2000,
            "focusPoint": {
              "xPct": 50,
              "yPct": 50
            },
            "id": "ef_abc123",
            "scale": 2,
            "startTimeMs": 1000,
            "type": "manualZoom"
          }
        ]
      }
    ],
    "video": {
      "backgroundMusic": {
        "durationMs": 180036,
        "name": "Calm Product Tour",
        "url": "https://ucarecdn.com/example-track/",
        "volume": 0.2
      },
      "chapters": [
        {
          "description": "Overview of what we'll cover",
          "title": "Introduction"
        }
      ],
      "settings": {
        "allowedEmbedDomains": [
          "example.com",
          "mysite.org"
        ],
        "captionGrouping": "chunked",
        "captionSize": "medium",
        "captionStyle": {
          "backgroundColor": "#5E51F8FF",
          "textColor": "#5E51F8FF"
        },
        "captionsDefaultEnabled": true,
        "commentsEnabled": true,
        "cursor": {
          "size": 3.05,
          "style": "macTahoe"
        },
        "customThumbnailURL": "https://example.com/custom-thumbnail.jpg",
        "defaultClipTransition": "smooth",
        "defaultPlaybackRate": 1,
        "downloadsEnabled": true,
        "linkScope": "org",
        "microphoneVolume": 1,
        "motionBlur": true,
        "publishDateEnabled": true,
        "searchEngineIndexingEnabled": true,
        "shrinkCameraDuringZooms": true,
        "subtitlesEnabled": true,
        "systemAudioVolume": 1,
        "thumbnailInpointMs": 12000,
        "transcriptsEnabled": true,
        "viewCountEnabled": true
      }
    }
  },
  "video": {
    "aspectRatio": "16:9"
  }
}

Changes

Changed in 1 of the 3 revisions of this API.1

Sep 3, 2026841897ed76ba1See the full diff
- ○
  added the required property /////////////// to the response with the status
  response-required-property-added

Full history