> ## 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. # List File Segmentations > List all segmentations for a specific file ## OpenAPI ````yaml GET /files/{file_id}/segmentations 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.13 servers: - url: https://api.cloudglue.dev/v1 security: - bearerAuth: [] paths: /files/{file_id}/segmentations: get: tags: - Files summary: List segmentations for a file description: List all segmentations for a specific file operationId: listFileSegmentations parameters: - name: file_id in: path required: true description: The ID of the file schema: type: string format: uuid - name: limit in: query description: Number of segmentations to return required: false schema: type: integer maximum: 100 minimum: 1 - name: offset in: query description: Offset from the start of the list required: false schema: type: integer minimum: 0 responses: '200': description: List of segmentations content: application/json: schema: $ref: '#/components/schemas/SegmentationList' '404': description: File 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: SegmentationList: type: object required: - object - data - total - limit - offset properties: object: type: string enum: - list description: Object type, always 'list' data: type: array items: $ref: '#/components/schemas/SegmentationListItem' description: Array of segmentation objects total: type: integer description: Total number of segmentations matching the query limit: type: integer description: Number of items returned in this response offset: type: integer description: Offset from the start of the list Error: required: - error type: object properties: error: type: string SegmentationListItem: type: object required: - segmentation_id - status - created_at - file_id - segmentation_config - thumbnails_config properties: segmentation_id: type: string format: uuid description: Unique identifier for the segmentation job status: type: string enum: - pending - processing - completed - failed - not_applicable description: >- 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: type: number minimum: 0 description: Unix timestamp in milliseconds when the segmentation was created file_id: type: string format: uuid description: ID of the file this segmentation belongs to segmentation_config: $ref: '#/components/schemas/SegmentationConfig' thumbnails_config: $ref: '#/components/schemas/ThumbnailsConfig' total_segments: type: number minimum: 0 description: >- Total number of segments in this segmentation (only present when status is completed) description: >- Segmentation object as returned in list responses (does not include segments array or data property) SegmentationConfig: type: object description: >- 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. required: - strategy properties: strategy: type: string enum: - uniform - shot-detector - manual - narrative description: Segmentation strategy - determines which config you must provide uniform_config: $ref: '#/components/schemas/SegmentationUniformConfig' description: >- 🎯 **REQUIRED when strategy = 'uniform'** - Configuration for uniform segmentation. shot_detector_config: $ref: '#/components/schemas/SegmentationShotDetectorConfig' description: >- 🎯 **REQUIRED when strategy = 'shot-detector'** - Configuration for shot detection segmentation. manual_config: $ref: '#/components/schemas/SegmentationManualConfig' description: >- 🎯 **REQUIRED when strategy = 'manual'** - Configuration for manual segmentation. narrative_config: $ref: '#/components/schemas/NarrativeConfig' description: >- 🎯 **REQUIRED when strategy = 'narrative'** - Configuration for narrative-based chapter segmentation using AI analysis. keyframe_config: $ref: '#/components/schemas/KeyframeConfig' description: >- When provided, will be used to extract keyframes for the segmentation. start_time_seconds: type: number minimum: 0 description: >- Optional: The start time of the video in seconds to start segmenting from end_time_seconds: type: number minimum: 0 description: 'Optional: The end time of the video in seconds to stop segmenting at' ThumbnailsConfig: type: object required: - enable_segment_thumbnails properties: enable_segment_thumbnails: type: boolean description: >- Whether to enable segment thumbnails. If not provided will use default to false. Cannot be used together with segmentation_id. SegmentationUniformConfig: type: object required: - window_seconds properties: window_seconds: type: number minimum: 1 maximum: 120 description: >- The duration of each segment in seconds. Must be between 1 and 120 seconds. hop_seconds: type: number minimum: 1 maximum: 120 description: >- 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. SegmentationShotDetectorConfig: type: object required: - detector properties: threshold: type: number nullable: true description: >- 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: type: number minimum: 0.6 maximum: 600 nullable: true description: The minimum length of a shot in seconds. Defaults to 0.6. max_seconds: type: number minimum: 1 maximum: 600 nullable: true description: The maximum length of a shot in seconds. Defaults to 300. detector: type: string enum: - adaptive - content description: >- 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: type: boolean description: >- 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. SegmentationManualConfig: type: object required: - segments properties: segments: type: array items: type: object properties: start_time: type: number description: The start time of the segment in seconds end_time: type: number description: The end time of the segment in seconds description: Array of segments NarrativeConfig: type: object properties: prompt: type: string description: >- Optional custom prompt to guide the narrative segmentation analysis. This will be incorporated into the main segmentation prompt as additional guidance. strategy: type: string enum: - comprehensive - balanced - transcript description: >- 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: type: integer minimum: 1 description: >- 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: type: integer minimum: 1 description: >- 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: type: integer minimum: 1 description: >- 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. KeyframeConfig: type: object required: - frames_per_segment description: >- Configuration for keyframe extraction. When provided, will be used to extract keyframes for the segmentation. This is not supported for YouTube videos. properties: frames_per_segment: type: number minimum: 0 maximum: 8 description: The number of key frames to extract per segment max_width: type: number minimum: 144 maximum: 4320 description: The maximum width of the key frames in pixels securitySchemes: bearerAuth: type: http scheme: bearer ````