---
title: "Retrieve details about a specific collection"
method: GET
path: "/collections/{collection_id}"
tags: ["Collections"]
---

# Retrieve details about a specific collection

`GET /collections/{collection_id}`

## Request

- Base URL: `https://api.cloudglue.dev/v1`
- URL: `https://api.cloudglue.dev/v1/collections/{collection_id}`
- Auth: HTTP bearer

Retrieve details about a specific collection

## Path parameters

- `collection_id` string, required

## Response `200`

Collection details

- Collection
  - `id` string, required: Unique identifier for the collection
  - `object` 'collection', required: Object type, always 'collection'
  - `name` string, required: Name of the collection
  - `description` string, nullable: Description of the collection's purpose or contents, null if none provided
  - `collection_type` 'media-descriptions' | 'entities' | 'rich-transcripts' | 'face-analysis' | 'metadata' | 'moments', required: Type of collection, determines how videos are processed and what data is extracted
  - `moments_config` object: Moments collections only: the criteria echo with per-attachment state (live counters on single GETs).
    - `criteria` MomentCriterionAttachment[]
      - `attachment_id` string, uuid, required
      - `criterion_name` string, required
      - `criterion_hash` string, required
      - `criterion` MomentCriterion: An inline criterion: rubric instructions plus typed output declarations. Snapshotted and hashed onto the run.
        - `name` string, required
        - `instructions` string, required: The complete rubric, including any seed lists and worked examples.
        - `moment_schema` MomentSchemaDefinition: A validated JSON Schema subset (the moment schema dialect): a root object of string/number/integer/boolean/array-of-those fields, optional enums, one nesting level, per-field descriptions. Rejected shapes get a field-addressable 400 with a stable code.
        - `finding_schema` MomentSchemaDefinition: A validated JSON Schema subset (the moment schema dialect): a root object of string/number/integer/boolean/array-of-those fields, optional enums, one nesting level, per-field descriptions. Rejected shapes get a field-addressable 400 with a stable code.
        - `anchors` object: Named intra-moment timestamps. A non-required anchor that does not exist is omitted from the moment - never null.
        - `scoring` object: The rubric's single canonical score: what rank-ordered reads sort by and what min_score filters on. Exactly one scoring key per criterion.
          - `key` string, required
          - `min` number, required
          - `max` number, required
          - `higher_is_better` boolean
          - `description` string
      - `options` object: The per-attachment run knobs, as supplied on NewMomentCriterionAttachment.
        - `signals_required` string[]
        - `boundary_policy` 'sentence' | 'tight' | 'loose'
        - `speaker_filter` object
        - `min_duration_seconds` number
        - `max_duration_seconds` number
      - `backfill_status` 'pending' | 'processing' | 'completed' | 'completed_with_failures', required
      - `files_total` integer
      - `files_completed` integer
      - `files_failed` integer
      - `created_at` integer: Unix timestamp in milliseconds
  - `extract_config` object: Configuration for automatic entity extraction from videos. Required when collection_type is 'entities'.
    - `prompt` string: A natural language prompt describing the data to extract. Required if no schema is provided.
    - `schema` object: A more rigid structure if you already know the JSON layout you want. Required if no prompt is provided.
    - `enable_video_level_entities` boolean: Whether to extract entities at the video level. Mutually exclusive with enable_segment_level_entities - only one can be true.
    - `enable_segment_level_entities` boolean: Whether to extract entities at the segment level. Mutually exclusive with enable_video_level_entities - only one can be true.
    - `enable_transcript_mode` boolean: When enabled, extract entities from transcript only. Useful for speech-heavy content.
    - `enable_metadata_mode` boolean: When enabled, every file added to this entities collection is extracted from its metadata document (filename, file details, user metadata, and connector source metadata) instead of the media content. File-level entities only; flat 1 credit per file; metadata-only files are never ingested. Mutually exclusive with enable_transcript_mode.
  - `transcribe_config` object: Configuration for rich transcription from videos. Used when collection_type is 'rich-transcripts'. If not provided, default values will be used.
    - `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_scene_text` boolean: Whether to generate scene text extraction
    - `enable_visual_scene_description` boolean: Whether to generate visual scene description
    - `enable_audio_description` boolean: Whether to generate audio description
  - `describe_config` object: Configuration for comprehensive media description from videos. Used when collection_type is 'media-descriptions'. If not provided, default values will be used.
    - `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_scene_text` boolean: Whether to generate scene text extraction
    - `enable_visual_scene_description` boolean: Whether to generate visual scene description
    - `enable_audio_description` boolean: Whether to generate audio description
    - `prompt` string: Optional free-form guidance applied when describing every file in the collection. Use it to name the terms, product names, acronyms, or people that matter for this collection and how they are spelled, or to say what the descriptions 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 a description report content that is not in the media, and it does not change the response shape. Like the rest of the describe config it is fixed at creation — files already in the collection were described under the original guidance.
  - `default_segmentation_config` SegmentationConfig: 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
  - `default_thumbnails_config` ThumbnailsConfig
    - `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.
  - `face_detection_config` object, nullable: Configuration for face detection in videos. Only present when collection_type is 'face-analysis'.
    - `frame_extraction_config` object
      - `strategy` 'uniform', required: Frame extraction strategy
      - `uniform_config` object
        - `frames_per_second` number: Number of frames to extract per second
        - `max_width` number: Maximum width of frames in pixels (aspect ratio preserved)
    - `thumbnails_config` object
      - `enable_frame_thumbnails` boolean: Whether to generate thumbnails for extracted frames
  - `created_at` integer, required: Unix timestamp in milliseconds when the collection was created
  - `file_count` integer, required: Number of files in the collection

## Other responses

- `404`: Collection 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-08-31** `85130a1f5247`: 1 info
  - added the optional property `describe_config/prompt` to the response with the `200` status
- **2026-08-22** `d2a5205fc779`: 1 warning, 1 info
  - added the new `moments` enum value to the `collection_type` response property for the response status `200`
  - added the optional property `moments_config` to the response with the `200` status
- **2026-07-24** `915ee485b763`: 1 info
  - added the optional property `extract_config/enable_metadata_mode` to the response with the `200` status
- **2026-07-22** `c02e52ec2e28`: 1 warning
  - added the new `metadata` enum value to the `collection_type` response property for the response status `200`

[Operation history](https://skmtc.dev/cloudglue/apis/cloudglue-api/changes/collections/:collection_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)