Skip to main content
GET
Retrieve the current state of a media description job

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

job_id
string
required

The unique identifier of the description job

Query Parameters

response_format
enum<string>

Format for the response. Use speech_srt or speech_vtt for subtitle formats, speech_markdown for a diarized transcript, or speech_text for plain timestamped text.

Available options:
json,
markdown,
speech_srt,
speech_vtt,
speech_markdown,
speech_text
start_time_seconds
number

Start time in seconds to filter out results by

end_time_seconds
number

End time in seconds to filter out results by

modalities
enum<string>[]

The modalities to output in the response. Can be used to return smaller data sets. Comma separated list of strings. Defaults to all modalities available / previously extracted. Accepted values are speech,visual_scene_description,scene_text, audio_description, summary, segment_summary, title

Available options:
speech,
visual_scene_description,
scene_text,
audio_description,
summary,
segment_summary,
title
include_thumbnails
boolean

When true, include a file-level thumbnail_url on the response, per-segment thumbnail_url on each segment_summary entry, and inject thumbnail images into markdown output

include_word_timestamps
boolean
default:false

When true, include a words array on each speech entry with word-level start_time and end_time. Not available for YouTube sources. Only applies when response_format=json.

include_chapters
boolean
default:false

Include narrative chapters in the response (when segmentation strategy is 'narrative')

include_shots
boolean
default:false

Include shot boundaries in the response (when segmentation strategy is 'shot-detector')

Response

Successful response with job details

job_id
string
required
status
enum<string>
required
Available options:
pending,
processing,
completed,
failed,
not_applicable
url
string

The URL of the processed video

duration_seconds
number

Duration of the video in seconds

thumbnail_url
string<uri>

URL of the file-level thumbnail for the video. Only present when include_thumbnails=true.

created_at
integer

Unix timestamp in milliseconds when the job was created

describe_config
object

Configuration for media description from videos

use_in_default_index
boolean

Whether this describe job's search documents are included in the default index.

data
object
error
string

Error message if status is 'failed'

segmentation_id
string<uuid>

The ID of the segmentation job if the describe was run with a segmentation

chapters
object[]

Array of narrative chapters (only present when include_chapters=true and segmentation strategy is 'narrative')

shots
object[]

Array of shot boundaries (only present when include_shots=true and segmentation strategy is 'shot-detector')

total_chapters
integer

Total number of chapters (only present when include_chapters=true and segmentation strategy is 'narrative')

Required range: x >= 0
total_shots
integer

Total number of shots (only present when include_shots=true and segmentation strategy is 'shot-detector')

Required range: x >= 0