---
title: "Get describe for a file segment"
method: GET
path: "/files/{file_id}/segments/{segment_id}/describes/{job_id}"
tags: ["Files", "File Segments", "Describe"]
---

# Get describe for a file segment

`GET /files/{file_id}/segments/{segment_id}/describes/{job_id}`

## Request

- Base URL: `https://api.cloudglue.dev/v1`
- URL: `https://api.cloudglue.dev/v1/files/{file_id}/segments/{segment_id}/describes/{job_id}`
- Auth: HTTP bearer

Get a specific describe output for a file segment by job ID

## Path parameters

- `file_id` string, uuid, required
- `segment_id` string, uuid, required
- `job_id` string, uuid, required

## Query parameters

- `response_format` 'json' | 'markdown'

## Response `200`

Describe for the segment

- SegmentDescribe: Describe output for a specific video segment
  - `job_id` string, uuid, required: The ID of the describe job
  - `segment_id` string, uuid, required: The ID of the video segment
  - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'not_applicable', required: Status of the describe job
  - `describe_config` DescribeConfig, required: Configuration for media description from videos
    - `enable_summary` boolean: Whether to generate video-level and segment-level (moment-level) summaries and titles
    - `enable_speech` boolean: Whether to generate speech transcript
    - `enable_visual_scene_description` boolean: Whether to generate visual scene description
    - `enable_scene_text` boolean: Whether to generate scene text extraction
    - `enable_audio_description` boolean: Whether to generate audio description
    - `prompt` string: Optional free-form guidance for the description. Use it to name the terms, product names, acronyms, or people that matter for this media and how they are spelled, or to say what the description should pay attention to — e.g. "Spell product names as Cloudglue and Aviary; call out any pricing discussed". It steers emphasis and vocabulary across the visual, scene-text, speech, and summary passes; it cannot make the description report content that is not in the media, and it does not change the response shape. To *constrain* transcript speaker labels to a known cast, use `participants` instead — a prompt is context, not a constraint. Changing it produces a new describe job rather than reusing a cached one.
  - `created_at` integer, required: Unix timestamp in milliseconds when the job was created
  - `completed_at` integer: Unix timestamp in milliseconds when the job completed
  - `start_time` number, required: Start time of the segment in seconds
  - `end_time` number, required: End time of the segment in seconds
  - `file_id` string, uuid, required: The ID of the file
  - `segmentation_id` string, uuid: The ID of the segmentation job
  - `data` union: The describe output data. When response_format=json, contains visual_scene_description, speech, scene_text, and audio_description arrays. When response_format=markdown, contains a content string.
    - SegmentDescribeJsonData: JSON format describe output data
      - `visual_scene_description` SegmentDescribeOutputEntry[]: Visual scene descriptions with timestamps
        - `text` string, required: The text content
        - `start_time` number, required: Start time in seconds
        - `end_time` number, required: End time in seconds
      - `speech` SegmentDescribeSpeechEntry[]: Speech transcript with timestamps and speaker info
        - `text` string, required: The speech text
        - `start_time` number, required: Start time in seconds
        - `end_time` number, required: End time in seconds
        - `speaker` string: Speaker identifier
      - `scene_text` SegmentDescribeOutputEntry[]: On-screen text detected with timestamps
        - `text` string, required: The text content
        - `start_time` number, required: Start time in seconds
        - `end_time` number, required: End time in seconds
      - `audio_description` SegmentDescribeOutputEntry[]: Audio descriptions with timestamps
        - `text` string, required: The text content
        - `start_time` number, required: Start time in seconds
        - `end_time` number, required: End time in seconds
      - `title` string: Generated title for the segment
      - `summary` string: Generated summary for the segment
      - `start_time` number: Start time of the segment in seconds
      - `end_time` number: End time of the segment in seconds
      - `segment_id` string, uuid: The ID of the segment
    - SegmentDescribeMarkdownData: Markdown format describe output data
      - `content` string, required: Markdown formatted content containing the describe output
  - `object` 'segment_describe', required: Object type

## Other responses

- `404`: File, segment, or describe job not found

## Changes

- **2026-10-30** `23d3f240819f`: 1 info
  - added the optional property `code` to the response with the `404` status
- **2026-08-31** `85130a1f5247`: 1 info
  - added the optional property `describe_config/prompt` to the response with the `200` status
- **2026-03-11** `1d5d6115c0d0`: 1 breaking, 5 info
  - for the `query` request parameter `response_format`, default value `json` was removed
  - the `enable_audio_description` response's property default value `false` was removed for the status `200`
  - the `enable_scene_text` response's property default value `true` was removed for the status `200`
  - the `enable_speech` response's property default value `true` was removed for the status `200`
  - …2 more
- **2026-01-30** `2e7f65543b55`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/cloudglue/apis/cloudglue-api/changes/files/:file_id/segments/:segment_id/describes/:job_id/get.md)

---

[API](https://skmtc.dev/cloudglue/apis/cloudglue-api.md) - [All operations](https://skmtc.dev/cloudglue/apis/cloudglue-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cloudglue/apis/cloudglue-api/revisions/23d3f240819f?raw)