--- title: "List segmentations for a file" method: GET path: "/files/{file_id}/segmentations" tags: ["Files"] --- # List segmentations for a file `GET /files/{file_id}/segmentations` ## Request - Base URL: `https://api.cloudglue.dev/v1` - URL: `https://api.cloudglue.dev/v1/files/{file_id}/segmentations` - Auth: HTTP bearer List all segmentations for a specific file ## Path parameters - `file_id` string, uuid, required ## Query parameters - `limit` integer - `offset` integer ## Response `200` List of segmentations - SegmentationList - `object` 'list', required: Object type, always 'list' - `data` SegmentationListItem[], required: Array of segmentation objects - `segmentation_id` string, uuid, required: Unique identifier for the segmentation job - `status` 'pending' | 'processing' | 'completed' | 'failed' | 'not_applicable', required: Status of the segmentation job. If a job has the status 'not_applicable' it means that we were unable to find any appropriate scenes for this video. This can be possible if you use the shot-detector strategy. - `created_at` number, required: Unix timestamp in milliseconds when the segmentation was created - `file_id` string, uuid, required: ID of the file this segmentation belongs to - `segmentation_config` SegmentationConfig, required: Configuration for video segmentation. **Choose a strategy and provide ONLY the corresponding config:** • **uniform**: Provide `uniform_config`, do NOT provide other configs • **shot-detector**: Provide `shot_detector_config`, do NOT provide other configs • **manual**: Provide `manual_config`, do NOT provide other configs • **narrative**: Provide `narrative_config`, do NOT provide other configs Optionally specify `start_time_seconds` and `end_time_seconds` to limit segmentation to a portion of the video. - `strategy` 'uniform' | 'shot-detector' | 'manual' | 'narrative', required: Segmentation strategy - determines which config you must provide - `uniform_config` SegmentationUniformConfig - `window_seconds` number, required: The duration of each segment in seconds. Must be between 1 and 120 seconds. - `hop_seconds` number: The offset between the start of new windows. This means there can be overlap between segments. If not provided, defaults to window_seconds. Must be between 1 and 120 seconds. - `shot_detector_config` SegmentationShotDetectorConfig - `threshold` number, nullable: Detection sensitivity threshold - lower values create more segments: • **content**: Sensitivity to visual differences (default: 27.0). Lower values detect smaller changes in color/lighting. • **adaptive**: Does not support threshold parameter - uses internal adaptive algorithm. - `min_seconds` number, nullable: The minimum length of a shot in seconds. Defaults to 0.6. - `max_seconds` number, nullable: The maximum length of a shot in seconds. Defaults to 300. - `detector` 'adaptive' | 'content', required: The detector strategy to use: • **adaptive**: Designed for dynamic footage with camera movement, panning, or action. Examples: sports broadcasts, drone footage, handheld documentaries, action movies, live events. • **content**: Optimized for controlled footage with clear visual transitions. Examples: studio interviews, corporate videos, educational content, product demos, scripted content. - `fill_gaps` boolean: When true, gaps between detected shots are filled: gaps greater than or equal to min_seconds become their own segments (split by max_seconds if needed), and shorter gaps are merged into the nearest adjacent segment. Defaults to true. - `manual_config` SegmentationManualConfig - `segments` object[], required: Array of segments - `start_time` number: The start time of the segment in seconds - `end_time` number: The end time of the segment in seconds - `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. - `keyframe_config` KeyframeConfig: Configuration for keyframe extraction. When provided, will be used to extract keyframes for the segmentation. This is not supported for YouTube videos. - `frames_per_segment` number, required: The number of key frames to extract per segment - `max_width` number: The maximum width of the key frames in pixels - `start_time_seconds` number: Optional: The start time of the video in seconds to start segmenting from - `end_time_seconds` number: Optional: The end time of the video in seconds to stop segmenting at - `thumbnails_config` ThumbnailsConfig, required - `enable_segment_thumbnails` boolean, required: Whether to enable segment thumbnails. If not provided will use default to false. Cannot be used together with segmentation_id. - `total_segments` number: Total number of segments in this segmentation (only present when status is completed) - `total` integer, required: Total number of segmentations matching the query - `limit` integer, required: Number of items returned in this response - `offset` integer, required: Offset from the start of the list ## Other responses - `404`: File 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`: 1 breaking - the `data/items/segmentation_config/shot_detector_config/min_seconds` response property's min was decreased from `1.00` to `0.60` for the response status `200` - **2026-04-27** `43191ed5a246`: 1 warning - added the new `transcript` enum value to the `data/items/segmentation_config/narrative_config/strategy` response property for the response status `200` - **2026-03-11** `1d5d6115c0d0`: 2 breaking, 5 info - for the `query` request parameter `limit`, default value `50` was removed - for the `query` request parameter `offset`, default value `0` was removed - the `fill_gaps` response's property default value `true` was removed for the status `200` - the `max_seconds` response's property default value `300` was removed for the status `200` - …3 more - …earlier changes not shown [Operation history](https://skmtc.dev/cloudglue/apis/cloudglue-api/changes/files/:file_id/segmentations/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)