> ## 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 Videos in Collection > List all files in a collection ## OpenAPI ````yaml GET /collections/{collection_id}/videos 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.8 servers: - url: https://api.cloudglue.dev/v1 security: - bearerAuth: [] paths: /collections/{collection_id}/videos: get: tags: - Collections summary: List all files in a collection description: List all files in a collection operationId: listVideos parameters: - name: collection_id in: path required: true description: The ID of the collection schema: type: string - name: limit in: query description: Maximum number of files to return required: false schema: type: integer maximum: 100 - name: offset in: query description: Number of files to skip required: false schema: type: integer - name: status in: query description: Filter by processing status required: false schema: type: string enum: - pending - processing - completed - failed - not_applicable - name: added_before in: query description: >- Filter files added before a specific date (YYYY-MM-DD format), in UTC timezone required: false schema: type: string format: date - name: added_after in: query description: >- Filter files added after a specific date (YYYY-MM-DD format), in UTC timezone required: false schema: type: string format: date - name: order in: query description: Order the files by a specific field required: false schema: type: string enum: - added_at - filename - name: sort in: query description: Sort the files in ascending or descending order required: false schema: type: string enum: - asc - desc - name: filter in: query description: >- JSON string containing filter criteria to constrain file search results. This is the JSON string version of the SearchFilter object used in the search API. **Supported Filter Types:** • **metadata** - Filter by file metadata using JSON path expressions (e.g., 'metadata.speaker', 'metadata.category.subcategory') • **video_info** - Filter by video information properties. Supports optional `scope` ('file' or 'segment', default 'file') - `duration_seconds` - Video/segment duration in seconds (supports file and segment scope) - `has_audio` - Whether the video has audio (true/false, file scope only) • **file** - Filter by file properties - `filename` - File name (string) - `uri` - File URI (string) - `id` - File ID (UUID string) - `created_at` - Creation timestamp (ISO 8601 string) - `bytes` - File size in bytes (number) **Supported Operators:** • **Equal** - Exact match (requires valueText) • **NotEqual** - Not equal to value (requires valueText) • **LessThan** - Less than value (requires valueText) • **GreaterThan** - Greater than value (requires valueText) • **Like** - Case-insensitive pattern matching with wildcards (requires valueText) • **In** - Value is in array (requires valueTextArray) • **ContainsAny** - Array contains any of the values (requires valueTextArray) • **ContainsAll** - Array contains all of the values (requires valueTextArray) **Examples:** **Metadata filtering:** ```json {"metadata":[{"path":"speaker","operator":"Like","valueText":"YO%"}]} ``` **Video info filtering (file-level):** ```json {"video_info":[{"path":"duration_seconds","operator":"GreaterThan","valueText":"60"}]} ``` **Video info filtering (segment-level):** ```json {"video_info":[{"path":"duration_seconds","operator":"LessThan","valueText":"30","scope":"segment"}]} ``` **File property filtering:** ```json {"file":[{"path":"filename","operator":"Like","valueText":"%.mp4"}]} ``` ```json {"file":[{"path":"bytes","operator":"GreaterThan","valueText":"1048576"}]} ``` ```json {"file":[{"path":"created_at","operator":"GreaterThan","valueText":"2024-01-01T00:00:00Z"}]} ``` **Combined filtering:** ```json {"metadata":[{"path":"speaker","operator":"Equal","valueText":"John"}],"video_info":[{"path":"has_audio","operator":"Equal","valueText":"true"}],"file":[{"path":"filename","operator":"Like","valueText":"%.mp4"}]} ``` required: false schema: type: string responses: '200': description: A list of files in the collection content: application/json: schema: $ref: '#/components/schemas/CollectionFileList' '404': description: Collection 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: CollectionFileList: type: object properties: object: type: string enum: - list description: Object type, always 'list' data: type: array items: $ref: '#/components/schemas/CollectionFile' description: Array of collection file objects total: type: integer description: Total number of files 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 required: - object - data - total - limit - offset Error: required: - error type: object properties: error: type: string CollectionFile: type: object properties: collection_id: type: string description: ID of the collection file_id: type: string description: ID of the file object: type: string enum: - collection_file description: Object type, always 'collection_file' added_at: type: integer description: >- Unix timestamp in milliseconds when the file was added to the collection status: type: string enum: - pending - processing - completed - failed - not_applicable description: Overall processing status of the file in this collection file: $ref: '#/components/schemas/File' description: The file object segmentation: type: object description: >- Segmentation information for this file in the collection. Only present when the file has been segmented. properties: id: type: string format: uuid description: Unique identifier for the segmentation status: type: string enum: - pending - processing - completed - failed - not_applicable description: Status of the segmentation job file_id: type: string format: uuid description: ID of the file that was segmented segmentation_config: $ref: '#/components/schemas/SegmentationConfig' description: Configuration used for this segmentation required: - id - status - file_id - segmentation_config required: - collection_id - file_id - object - added_at - status File: type: object properties: id: type: string description: Unique identifier for the file status: type: string enum: - pending - processing - completed - failed - not_applicable description: Processing status of the file bytes: type: integer nullable: true description: Size of the file in bytes, null if not available created_at: type: integer description: Unix timestamp in milliseconds when the file was created filename: type: string description: Original filename uri: type: string description: Cloudglue URI for the file, to be used in other API calls metadata: type: object nullable: true description: User-provided metadata about the file, null if none provided media_type: type: string enum: - video - audio - image description: >- Type of media file (video, audio, or image). Images are processed at the file level only (no segmentation). media_info: type: object properties: duration_seconds: type: number nullable: true description: Duration in seconds width: type: integer nullable: true description: Width in pixels (null for audio files) height: type: integer nullable: true description: Height in pixels (null for audio files) sample_rate: type: integer nullable: true description: Audio sample rate in Hz channels: type: integer nullable: true description: Number of audio channels bitrate: type: integer nullable: true description: Audio bitrate in bps format: type: string nullable: true description: File format has_audio: type: boolean nullable: true description: Whether the file has audio description: Unified media information for video, audio, and image files video_info: type: object properties: duration_seconds: type: number nullable: true description: Duration of the video in seconds, null if not available height: type: integer nullable: true description: Height of the video in pixels, null if not available width: type: integer nullable: true description: Width of the video in pixels, null if not available format: type: string nullable: true description: Format of the video file, null if not available has_audio: type: boolean nullable: true description: Whether the video has audio, null if not available description: Information about the video content thumbnail_url: type: string description: URL of the thumbnail for the file source: type: string enum: - video - youtube - s3 - dropbox - http - upload - google-drive - zoom - gong - recall - gcs - grain - loom description: Source of the file source_metadata: allOf: - $ref: '#/components/schemas/SourceMetadata' nullable: true description: >- Source provenance captured from the upstream connector at ingest time. Null when nothing was captured (older files, or a connector that does not yet populate it). required: - id - uri - status 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' SourceMetadata: oneOf: - $ref: '#/components/schemas/GrainSourceMetadata' discriminator: propertyName: source_type mapping: grain: $ref: '#/components/schemas/GrainSourceMetadata' description: >- Per-source provenance captured from the upstream connector. Currently only Grain is populated. 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 GrainSourceMetadata: type: object description: >- Source provenance captured from Grain at ingest time. The richer AI/contextual fields are only present when Grain returns them. properties: source_type: type: string enum: - grain description: Discriminator identifying the upstream connector. grain_recording_id: type: string description: Grain's recording id. title: type: string description: Recording title. start_datetime: type: string format: date-time description: UTC time Grain started the recording. end_datetime: type: string format: date-time description: UTC time the recording ended. duration_ms: type: integer description: Recording duration in milliseconds. media_type: type: string enum: - audio - transcript - video description: Grain media type of the recording. upstream_source: type: string enum: - aircall - local_capture - meet - teams - upload - webex - zoom - other description: Platform Grain captured the recording from. grain_url: type: string description: URL to the recording in Grain. thumbnail_url: type: string nullable: true description: Thumbnail URL, null if none. tags: type: array items: type: string description: Tags applied to the recording. teams: type: array items: type: object properties: id: type: string name: type: string description: Teams the recording belongs to. meeting_type: type: object nullable: true properties: id: type: string name: type: string scope: type: string description: Recording's meeting type, null if none. participants: type: array items: type: object properties: id: type: string name: type: string email: type: string nullable: true scope: type: string enum: - internal - external - unknown confirmed_attendee: type: boolean hs_contact_id: type: string nullable: true description: HubSpot contact id, if linked. nullable: true description: >- Meeting participants (include-gated by Grain). Null when requested but empty. highlights: type: array items: type: object nullable: true description: Clips / highlights (include-gated). Null when requested but empty. ai_summary: type: object properties: text: type: string description: Markdown AI summary. nullable: true description: AI summary (include-gated). Null when requested but empty. ai_action_items: type: array items: type: object properties: status: type: string enum: - pending - completed timestamp_ms: type: integer description: Time in the recording the item was mentioned. text: type: string assignee: type: object nullable: true properties: id: type: string name: type: string user_id: type: string nullable: true nullable: true description: AI action items (include-gated). Null when requested but empty. ai_template_sections: type: array items: type: object nullable: true description: >- AI template sections, shape varies by template (include-gated). Null when requested but empty. calendar_event: type: object nullable: true properties: ical_uid: type: string description: Related calendar event (include-gated). hubspot: type: object properties: hubspot_company_ids: type: array items: type: string hubspot_deal_ids: type: array items: type: string nullable: true description: >- Related HubSpot company/deal ids (include-gated). Null when requested but empty. required: - source_type - grain_recording_id - title - start_datetime - end_datetime - duration_ms - media_type - upstream_source - grain_url - tags - teams securitySchemes: bearerAuth: type: http scheme: bearer ````