> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudglue.dev/llms.txt > Use this file to discover all available pages before exploring further. # Get Media Description > Retrieve the current state of a media description job ## OpenAPI ````yaml GET /describe/{job_id} openapi: 3.0.0 info: title: Cloudglue API description: API for Cloudglue license: name: Apache License 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 version: 0.7.10 servers: - url: https://api.cloudglue.dev/v1 security: - bearerAuth: [] paths: /describe/{job_id}: get: tags: - Describe summary: Retrieve the current state of a media description job description: Retrieve the current state of a media description job operationId: getDescribe parameters: - name: job_id in: path required: true description: The unique identifier of the description job schema: type: string - name: response_format in: query description: >- 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. required: false schema: type: string enum: - json - markdown - speech_srt - speech_vtt - speech_markdown - speech_text - name: start_time_seconds in: query description: Start time in seconds to filter out results by required: false schema: type: number - name: end_time_seconds in: query description: End time in seconds to filter out results by required: false schema: type: number - name: modalities in: query required: false schema: $ref: '#/components/schemas/ModalitiesSchema' - name: include_thumbnails in: query description: >- 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 required: false schema: type: boolean - name: include_word_timestamps in: query description: >- 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. required: false schema: type: boolean default: false - name: include_chapters in: query description: >- Include narrative chapters in the response (when segmentation strategy is 'narrative') required: false schema: type: boolean default: false - name: include_shots in: query description: >- Include shot boundaries in the response (when segmentation strategy is 'shot-detector') required: false schema: type: boolean default: false responses: '200': description: Successful response with job details content: application/json: schema: $ref: '#/components/schemas/Describe' '404': description: Job not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: An unexpected error occurred on the server content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: ModalitiesSchema: type: array items: type: string enum: - speech - visual_scene_description - scene_text - audio_description - summary - segment_summary - title description: >- 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 Describe: required: - job_id - status type: object properties: job_id: type: string status: type: string enum: - pending - processing - completed - failed - not_applicable url: type: string description: The URL of the processed video duration_seconds: type: number description: Duration of the video in seconds thumbnail_url: type: string format: uri description: >- URL of the file-level thumbnail for the video. Only present when include_thumbnails=true. created_at: type: integer description: Unix timestamp in milliseconds when the job was created describe_config: type: object description: Configuration for media description from videos properties: enable_summary: type: boolean description: >- Whether the user requested to generate video-level and segment-level (moment-level) summaries and titles enable_speech: type: boolean description: Whether the user requested to generate speech transcript enable_visual_scene_description: type: boolean description: Whether the user requested to generate visual scene description enable_scene_text: type: boolean description: Whether the user requested to generate scene text enable_audio_description: type: boolean description: Whether the user requested to generate audio description participants: type: array maxItems: 50 description: >- Known participants on the recording. When provided, speaker naming is constrained to these people: transcript speaker labels will only use one of these names (or a generic "Speaker N"), never an invented name. Intended for uploaded files, which (unlike data-connector files such as Grain) carry no participant metadata; for connector files this is populated automatically and need not be supplied. items: type: object required: - name properties: name: type: string description: Participant display name, e.g. "Alice Smith". scope: type: string description: >- Optional free-form context for the participant, e.g. a role, affiliation, or "internal"/"external". Used only as naming context. use_in_default_index: type: boolean description: >- Whether this describe job's search documents are included in the default index. data: allOf: - type: object properties: content: type: string description: >- Content string returned based on formatting, e.g. set to markdown text when response_format=markdown is requested title: type: string description: >- Generated title of the video; for YouTube videos, this is the title of the video as it appears on YouTube summary: type: string description: >- Generated video level summary; for YouTube videos, this is the summary of the video as it appears on YouTube segment_summary: type: array description: >- Array of summary information for each segment of the video. Only available when enable_summary is set to true in the describe configuration. items: type: object properties: title: type: string description: Generated segment-level title summary: type: string description: Generated segment-level summary start_time: type: number description: Start time of segment in seconds end_time: type: number description: End time of segment in seconds thumbnail_url: type: string format: uri description: URL of the segment thumbnail, when available. - $ref: '#/components/schemas/DescribeOutput' error: type: string description: Error message if status is 'failed' segmentation_id: type: string format: uuid description: >- The ID of the segmentation job if the describe was run with a segmentation chapters: type: array description: >- Array of narrative chapters (only present when include_chapters=true and segmentation strategy is 'narrative') items: type: object properties: index: type: integer minimum: 0 start_time: type: number minimum: 0 end_time: type: number minimum: 0 description: type: string required: - index - start_time - end_time - description shots: type: array description: >- Array of shot boundaries (only present when include_shots=true and segmentation strategy is 'shot-detector') items: type: object properties: index: type: integer minimum: 0 start_time: type: number minimum: 0 end_time: type: number minimum: 0 required: - index - start_time - end_time total_chapters: type: integer minimum: 0 description: >- Total number of chapters (only present when include_chapters=true and segmentation strategy is 'narrative') total_shots: type: integer minimum: 0 description: >- Total number of shots (only present when include_shots=true and segmentation strategy is 'shot-detector') Error: required: - error type: object properties: error: type: string DescribeOutput: type: object properties: visual_scene_description: type: array description: Array of visual descriptions items: $ref: '#/components/schemas/DescribeOutputPart' scene_text: type: array description: Array of scene text extractions items: $ref: '#/components/schemas/DescribeOutputPart' speech: type: array description: Array of speech transcriptions items: $ref: '#/components/schemas/SpeechOutputPart' audio_description: type: array description: Array of audio descriptions items: $ref: '#/components/schemas/DescribeOutputPart' DescribeOutputPart: type: object properties: text: type: string description: Text content start_time: type: number description: Start time in seconds end_time: type: number description: End time in seconds SpeechOutputPart: type: object properties: speaker: type: string description: Identified speaker text: type: string description: Transcribed speech text start_time: type: number description: Start time of speech in seconds end_time: type: number description: End time of speech in seconds words: type: array description: >- Word-level timestamps. Only present when include_word_timestamps=true. Not available for YouTube sources. items: $ref: '#/components/schemas/WordTimestamp' WordTimestamp: type: object description: A single word with its timing information properties: word: type: string description: The word text start_time: type: number description: Start time of the word in seconds end_time: type: number description: End time of the word in seconds required: - word - start_time - end_time securitySchemes: bearerAuth: type: http scheme: bearer ````