curl --request GET \
--url https://api.tella.com/v1/videos/{id}/timeline \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.tella.com/v1/videos/{id}/timeline"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.tella.com/v1/videos/{id}/timeline', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tella.com/v1/videos/{id}/timeline",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.tella.com/v1/videos/{id}/timeline"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.tella.com/v1/videos/{id}/timeline")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tella.com/v1/videos/{id}/timeline")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"clips": [
{
"contents": {
"blurs": 4503599627370495,
"cuts": 4503599627370495,
"highlights": 4503599627370495,
"layouts": 4503599627370495,
"overlays": 4503599627370495,
"soundEffects": 4503599627370495,
"textOverlays": 4503599627370495,
"transcriptWords": 4503599627370495,
"zooms": 4503599627370495
},
"durationMs": 1,
"id": "<string>",
"name": "<string>",
"order": 0,
"timelineStartMs": 1
}
],
"included": [
"settings"
],
"video": {
"aspectRatio": "16:9",
"description": "<string>",
"dimensions": {
"height": 123,
"width": 123
},
"durationMs": 1,
"id": "<string>",
"name": "<string>",
"updatedAt": "<string>"
},
"details": {
"clips": [
{
"clipId": "<string>",
"background": {
"type": "solid",
"color": "#000000ff",
"gradientAngle": 45,
"gradientColor1": "#ff0080ff",
"gradientColor2": "#7928caff",
"imageUrl": "<string>",
"sourceId": "su_abc123",
"videoDurationSeconds": 12.4,
"videoUrl": "<string>"
},
"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": [
{
"id": "<string>",
"media": [
{
"type": "image",
"height": 0,
"imageUrl": "<string>",
"slot": "screen",
"sourceId": "<string>",
"width": 0
}
],
"durationMs": 5000,
"layout": {
"kind": "fullscreen",
"screenFit": "cover",
"style": "regular"
},
"startTimeMs": 0,
"transitionStyle": "spring"
}
],
"microphoneVolume": 1,
"overlays": [
{
"dimensions": {
"height": 540,
"width": 960
},
"durationMs": 5000,
"id": "ly_abc123",
"point": {
"xPct": 30,
"yPct": 30
},
"startTimeMs": 1000,
"type": "image",
"imageUrl": "<string>",
"name": "Logo",
"sourceId": "su_abc123"
}
],
"soundEffects": [
{
"durationMs": 3000,
"id": "ly_abc123",
"startTimeMs": 1000,
"volume": 1,
"name": "Whoosh",
"sourceId": "su_abc123"
}
],
"studioSound": true,
"systemAudioVolume": 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"
}
],
"transcript": {
"text": "<string>",
"wordCount": 4503599627370495
},
"words": [
{
"endTimeMs": 1800,
"hidden": false,
"index": 12,
"startTimeMs": 1500,
"text": "Hello"
}
],
"zooms": [
{
"durationMs": 2000,
"id": "ef_abc123",
"startTimeMs": 1000,
"type": "manualZoom",
"focusPoint": {
"xPct": 50,
"yPct": 50
},
"scale": 2
}
]
}
],
"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",
"timestampSeconds": 0,
"title": "Introduction"
}
],
"settings": {
"allowedEmbedDomains": [
"example.com",
"mysite.org"
],
"captionGrouping": "chunked",
"captionPosition": {
"x": 0.5,
"y": 0.5
},
"captionSize": "medium",
"captionStyle": {
"backgroundColor": "#5E51F8FF",
"name": "backdrop",
"textColor": "#5E51F8FF",
"wordLevelHighlights": true
},
"captionsDefaultEnabled": true,
"commentEmailsEnabled": false,
"commentsEnabled": true,
"customThumbnailURL": "https://example.com/custom-thumbnail.jpg",
"defaultPlaybackRate": 1,
"downloadsEnabled": true,
"linkScope": "org",
"microphoneVolume": 1,
"publishDateEnabled": true,
"rawDownloadsEnabled": false,
"searchEngineIndexingEnabled": true,
"studioSound": false,
"subtitlesEnabled": true,
"systemAudioVolume": 1,
"transcriptsEnabled": true,
"viewCountEnabled": true
}
}
}
}{
"error": {
"code": "bad_request",
"doc_url": "https://tella.tv/docs/api-reference/errors#bad-request",
"message": "The request was malformed or contained invalid parameters."
}
}{
"error": {
"code": "unauthorized",
"doc_url": "https://tella.tv/docs/api-reference/errors#unauthorized",
"message": "Authentication is required. Provide a valid API key."
}
}{
"error": {
"code": "forbidden",
"doc_url": "https://tella.tv/docs/api-reference/errors#forbidden",
"message": "You don't have permission to access this resource."
}
}{
"error": {
"code": "not_found",
"doc_url": "https://tella.tv/docs/api-reference/errors#not-found",
"message": "The requested resource was not found."
}
}{
"error": {
"code": "unprocessable_entity",
"doc_url": "https://tella.tv/docs/api-reference/errors#unprocessable-entity",
"message": "The request was well-formed but contained semantic errors."
}
}{
"error": {
"code": "rate_limit_exceeded",
"doc_url": "https://tella.tv/docs/api-reference/errors#rate-limit-exceeded",
"message": "You have exceeded the rate limit. Please slow down."
}
}{
"error": {
"code": "internal_server_error",
"doc_url": "https://tella.tv/docs/api-reference/errors#internal-server-error",
"message": "An unexpected error occurred on the server."
}
}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.
curl --request GET \
--url https://api.tella.com/v1/videos/{id}/timeline \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.tella.com/v1/videos/{id}/timeline"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.tella.com/v1/videos/{id}/timeline', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tella.com/v1/videos/{id}/timeline",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.tella.com/v1/videos/{id}/timeline"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.tella.com/v1/videos/{id}/timeline")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.tella.com/v1/videos/{id}/timeline")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"clips": [
{
"contents": {
"blurs": 4503599627370495,
"cuts": 4503599627370495,
"highlights": 4503599627370495,
"layouts": 4503599627370495,
"overlays": 4503599627370495,
"soundEffects": 4503599627370495,
"textOverlays": 4503599627370495,
"transcriptWords": 4503599627370495,
"zooms": 4503599627370495
},
"durationMs": 1,
"id": "<string>",
"name": "<string>",
"order": 0,
"timelineStartMs": 1
}
],
"included": [
"settings"
],
"video": {
"aspectRatio": "16:9",
"description": "<string>",
"dimensions": {
"height": 123,
"width": 123
},
"durationMs": 1,
"id": "<string>",
"name": "<string>",
"updatedAt": "<string>"
},
"details": {
"clips": [
{
"clipId": "<string>",
"background": {
"type": "solid",
"color": "#000000ff",
"gradientAngle": 45,
"gradientColor1": "#ff0080ff",
"gradientColor2": "#7928caff",
"imageUrl": "<string>",
"sourceId": "su_abc123",
"videoDurationSeconds": 12.4,
"videoUrl": "<string>"
},
"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": [
{
"id": "<string>",
"media": [
{
"type": "image",
"height": 0,
"imageUrl": "<string>",
"slot": "screen",
"sourceId": "<string>",
"width": 0
}
],
"durationMs": 5000,
"layout": {
"kind": "fullscreen",
"screenFit": "cover",
"style": "regular"
},
"startTimeMs": 0,
"transitionStyle": "spring"
}
],
"microphoneVolume": 1,
"overlays": [
{
"dimensions": {
"height": 540,
"width": 960
},
"durationMs": 5000,
"id": "ly_abc123",
"point": {
"xPct": 30,
"yPct": 30
},
"startTimeMs": 1000,
"type": "image",
"imageUrl": "<string>",
"name": "Logo",
"sourceId": "su_abc123"
}
],
"soundEffects": [
{
"durationMs": 3000,
"id": "ly_abc123",
"startTimeMs": 1000,
"volume": 1,
"name": "Whoosh",
"sourceId": "su_abc123"
}
],
"studioSound": true,
"systemAudioVolume": 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"
}
],
"transcript": {
"text": "<string>",
"wordCount": 4503599627370495
},
"words": [
{
"endTimeMs": 1800,
"hidden": false,
"index": 12,
"startTimeMs": 1500,
"text": "Hello"
}
],
"zooms": [
{
"durationMs": 2000,
"id": "ef_abc123",
"startTimeMs": 1000,
"type": "manualZoom",
"focusPoint": {
"xPct": 50,
"yPct": 50
},
"scale": 2
}
]
}
],
"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",
"timestampSeconds": 0,
"title": "Introduction"
}
],
"settings": {
"allowedEmbedDomains": [
"example.com",
"mysite.org"
],
"captionGrouping": "chunked",
"captionPosition": {
"x": 0.5,
"y": 0.5
},
"captionSize": "medium",
"captionStyle": {
"backgroundColor": "#5E51F8FF",
"name": "backdrop",
"textColor": "#5E51F8FF",
"wordLevelHighlights": true
},
"captionsDefaultEnabled": true,
"commentEmailsEnabled": false,
"commentsEnabled": true,
"customThumbnailURL": "https://example.com/custom-thumbnail.jpg",
"defaultPlaybackRate": 1,
"downloadsEnabled": true,
"linkScope": "org",
"microphoneVolume": 1,
"publishDateEnabled": true,
"rawDownloadsEnabled": false,
"searchEngineIndexingEnabled": true,
"studioSound": false,
"subtitlesEnabled": true,
"systemAudioVolume": 1,
"transcriptsEnabled": true,
"viewCountEnabled": true
}
}
}
}{
"error": {
"code": "bad_request",
"doc_url": "https://tella.tv/docs/api-reference/errors#bad-request",
"message": "The request was malformed or contained invalid parameters."
}
}{
"error": {
"code": "unauthorized",
"doc_url": "https://tella.tv/docs/api-reference/errors#unauthorized",
"message": "Authentication is required. Provide a valid API key."
}
}{
"error": {
"code": "forbidden",
"doc_url": "https://tella.tv/docs/api-reference/errors#forbidden",
"message": "You don't have permission to access this resource."
}
}{
"error": {
"code": "not_found",
"doc_url": "https://tella.tv/docs/api-reference/errors#not-found",
"message": "The requested resource was not found."
}
}{
"error": {
"code": "unprocessable_entity",
"doc_url": "https://tella.tv/docs/api-reference/errors#unprocessable-entity",
"message": "The request was well-formed but contained semantic errors."
}
}{
"error": {
"code": "rate_limit_exceeded",
"doc_url": "https://tella.tv/docs/api-reference/errors#rate-limit-exceeded",
"message": "You have exceeded the rate limit. Please slow down."
}
}{
"error": {
"code": "internal_server_error",
"doc_url": "https://tella.tv/docs/api-reference/errors#internal-server-error",
"message": "An unexpected error occurred on the server."
}
}Authorizations
API key obtained from your Tella account settings
Path Parameters
Unique video identifier
"vid_abc123def456"
Query Parameters
Comma-separated clip IDs to return details for. The complete ordered clip outline is always returned.
"scn_abc123,scn_def456"
Comma-separated details to include: all, settings, chapters, backgroundMusic, clipSettings, cuts, layouts, zooms, blurs, highlights, overlays, textOverlays, soundEffects, transcript, words. Default: none.
"layouts,zooms,words"
Response
The video's edit state
A compact video timeline with optional video-level and clip-level details
Complete clip outline in playback order
Show child attributes
Show child attributes
Detail categories included in this response
settings, chapters, backgroundMusic, clipSettings, cuts, layouts, zooms, blurs, highlights, overlays, textOverlays, soundEffects, transcript, words Minimal video timeline summary
Show child attributes
Show child attributes
Present only when at least one detail category is requested
Show child attributes
Show child attributes
Related topics
Get video chaptersGet a video thumbnail or animated previewModel Context Protocol (MCP)Get video informationGet video export statusWas this page helpful?