--- title: "Retrieve the current state of a segmentation job" method: GET path: "/segments/{job_id}" tags: ["Segments"] --- # Retrieve the current state of a segmentation job `GET /segments/{job_id}` ## Request - Base URL: `https://api.cloudglue.dev/v1` - URL: `https://api.cloudglue.dev/v1/segments/{job_id}` - Auth: HTTP bearer Retrieve the current state of a segmentation job ## Path parameters - `job_id` string, uuid, required ## Response `200` Successful response with job details - Segments - `job_id` string, uuid, required: Unique identifier for the segment job - `file_id` string, uuid, required: ID of the file this segment belongs to - `object` 'segments', required: Object type, always 'segments' - `status` 'pending' | 'processing' | 'completed' | 'failed', required: Current status of the segment job - `criteria` 'shot' | 'narrative', required: Segment criteria used for this job - `created_at` integer, required: Unix timestamp in milliseconds when the job was created - `shot_config` ShotConfig - `detector` 'content' | 'adaptive': Detection algorithm: • **adaptive**: Designed for dynamic footage with camera movement and action (default) • **content**: Optimized for controlled footage with clear visual transitions - `max_duration_seconds` number: Maximum duration for each segment in seconds (1 second to 10 minutes, default: 5 minutes) - `min_duration_seconds` number: Minimum duration for each segment in seconds (0.6 seconds to 10 minutes, default: 0.6 seconds) - `fill_gaps` boolean: When true, gaps between detected shots are filled: gaps greater than or equal to min_duration_seconds become their own segments (split by max_duration_seconds if needed), and shorter gaps are merged into the nearest adjacent segment. Defaults to true. - `narrative_config` NarrativeConfig - `prompt` string: Optional custom prompt to guide the narrative segmentation analysis. This will be incorporated into the main segmentation prompt as additional guidance. - `strategy` 'comprehensive' | 'balanced' | 'transcript': Narrative segmentation strategy: • **comprehensive**: Uses a VLM to deeply analyze logical segments of video. Only available for video files (not YouTube or audio). • **balanced** (default): Balanced analysis approach using multiple modalities. Supports YouTube URLs and audio files. • **transcript**: Cheap and fast speech-transcript-based segmentation. Requires a transcript; returns an error for silent or visual-only content (use `balanced` instead, or `comprehensive` for non-YouTube/non-audio video files). **Note**: YouTube URLs and audio files only support the **balanced** and **transcript** strategies; **comprehensive** will be rejected with an error. - `number_of_chapters` integer: Optional target number of chapters to generate. If provided, min_chapters and max_chapters will be calculated automatically if not specified. If only target is provided, the AI will attempt to generate exactly this number of chapters. - `min_chapters` integer: Optional minimum number of chapters to generate. If provided along with number_of_chapters and max_chapters, validates that min <= number_of_chapters <= max. If only number_of_chapters is provided, min and max are calculated automatically. - `max_chapters` integer: Optional maximum number of chapters to generate. If provided along with number_of_chapters and min_chapters, validates that min <= number_of_chapters <= max. If only number_of_chapters is provided, min and max are calculated automatically. - `total_segments` integer: Total number of segments generated (only present when status is 'completed') - `total_shots` integer: Total number of shots in the original video (only present when criteria is 'shot') - `total_chapters` integer: Total number of chapters in the video (only present when criteria is 'narrative') - `segments` Segment[]: Array of generated segments (only present when status is 'completed') - `start_time` number, required: Start time of the segment in seconds - `end_time` number, required: End time of the segment in seconds - `description` string: Optional description of the segment content (available for narrative segmentation) - `thumbnail_url` string, uri: Optional URL of the thumbnail for this segment - `shot_index` integer: Index of the shot in the original video segmentation. Only present when criteria is set to 'shot' - `shots` Shot[]: Array of shots in the original video (only present when criteria is 'shot') - `index` integer, required: Index of the shot in the original video - `start_time` number, required: Start time of the shot in seconds - `end_time` number, required: End time of the shot in seconds - `chapters` Chapter[]: Array of narrative chapters in the video (only present when criteria is 'narrative') - `index` integer, required: Index of the chapter in the video - `start_time` number, required: Start time of the chapter in seconds - `end_time` number, required: End time of the chapter in seconds - `description` string, required: AI-generated description of the chapter content ## Other responses - `404`: Job not found - `500`: An unexpected error occurred on the server ## Changes - **2026-10-30** `23d3f240819f`: 2 info - added the optional property `code` to the response with the `404` status - added the optional property `code` to the response with the `500` status - **2026-06-12** `f90a8032c6ae`: 3 breaking - the `shot_config/min_duration_seconds` response property's min was decreased from `1.00` to `0.60` for the response status `200` - the `shot_config/max_duration_seconds` response's property type changed from `integer` to `number` for status `200` - the `shot_config/min_duration_seconds` response's property type changed from `integer` to `number` for status `200` - **2026-04-27** `43191ed5a246`: 1 warning - added the new `transcript` enum value to the `narrative_config/strategy` response property for the response status `200` - **2026-03-11** `1d5d6115c0d0`: 5 info - the `detector` response's property default value `adaptive` was removed for the status `200` - the `fill_gaps` response's property default value `true` was removed for the status `200` - the `max_duration_seconds` response's property default value `300` was removed for the status `200` - the `min_duration_seconds` response's property default value `1` was removed for the status `200` - …1 more - **2026-03-09** `3700d31a3ff8`: 1 info - added the optional property `shot_config/fill_gaps` to the response with the `200` status [Operation history](https://skmtc.dev/cloudglue/apis/cloudglue-api/changes/segments/: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)