---
title: "Search across video files and segments to find relevant content"
method: POST
path: "/search"
tags: ["Search"]
---

# Search across video files and segments to find relevant content

`POST /search`

## Request

- Base URL: `https://api.cloudglue.dev/v1`
- URL: `https://api.cloudglue.dev/v1/search`
- Auth: HTTP bearer

Search for videos or video segments in collections to find relevant videos or moments/clips in a video

## Request body

- SearchRequest
  - `scope` 'file' | 'segment' | 'face' | 'moment': Search scope - 'file' searches at file level (requires collections with enable_summary=true), 'segment' searches at segment level, 'face' searches for faces in videos using image matching, 'moment' searches moments produced by find-moments criteria in moments collections
  - `collections` string[]: List of collection IDs to search within. For text search (scope='file' or 'segment'): All collections must be of collection_type 'media-descriptions', 'rich-transcripts', 'metadata', or 'entities'. For file-level search, 'media-descriptions' and 'rich-transcripts' collections must have 'enable_summary: true' in their config. 'metadata' collections only support scope='file'. 'entities' collections are searchable at the scope matching their extraction level: file-level extraction (enable_video_level_entities or enable_metadata_mode) supports scope='file' only, segment-level extraction (enable_segment_level_entities) supports scope='segment' only. For face search (scope='face'): All collections must be of collection_type 'face-analysis'. For moment search (scope='moment'): All collections must be of collection_type 'moments'.
  - `query` string: Text search query to find relevant content (required for scope='file', 'segment', or 'moment')
  - `criterion_name` string: Narrow moment search to one criterion by name (scope='moment' only)
  - `source_image` object: Source image for face search (required for scope='face')
    - `url` string: URL of the source image to search for
    - `base64` string: Base64-encoded image bytes
  - `limit` integer: Maximum number of search results to return (applies to total items across groups when grouping)
  - `filter` SearchFilter
    - `metadata` object[]: Filter by file metadata using JSON path expressions
      - `path` string, required: JSON path for the field to filter on
      - `operator` 'NotEqual' | 'Equal' | 'LessThan' | 'GreaterThan' | 'ContainsAny' | 'ContainsAll' | 'In' | 'Like', required: Comparison operator to apply
      - `valueText` string: Text value for scalar comparison (used with NotEqual, Equal, LessThan, GreaterThan, Like)
      - `valueTextArray` string[]: Array of values for array comparisons (used with ContainsAny, ContainsAll, In)
      - `scope` 'file' | 'segment': Specifies scope of eligible search items (file/segment) to check metadata filtering conditions
    - `video_info` object[]: Filter by video information. Use scope 'file' to filter by source video properties, or 'segment' to filter by individual segment properties (e.g. segment duration).
      - `path` 'duration_seconds' | 'has_audio', required: JSON path for the field to filter on
      - `operator` 'NotEqual' | 'Equal' | 'LessThan' | 'GreaterThan' | 'ContainsAny' | 'ContainsAll' | 'In' | 'Like', required: Comparison operator to apply
      - `valueText` string: Text value for scalar comparison (used with NotEqual, Equal, LessThan, GreaterThan, Like)
      - `valueTextArray` string[]: Array of values for array comparisons (used with ContainsAny, ContainsAll, In)
      - `scope` 'file' | 'segment': Scope of the filter. 'file' filters by source video properties, 'segment' filters by segment properties. Only duration_seconds is supported with segment scope.
    - `file` object[]: Filter by file properties
      - `path` 'bytes' | 'filename' | 'uri' | 'created_at' | 'id', required: JSON path for the field to filter on
      - `operator` 'NotEqual' | 'Equal' | 'LessThan' | 'GreaterThan' | 'ContainsAny' | 'ContainsAll' | 'In' | 'Like', required: Comparison operator to apply
      - `valueText` string: Text value for scalar comparison (used with NotEqual, Equal, LessThan, GreaterThan, Like)
      - `valueTextArray` string[]: Array of values for array comparisons (used with ContainsAny, ContainsAll, In)
    - `source_metadata` SearchFilterCriteria[]: Filter by connector-provided source metadata using JSON path expressions (file scope only). Available fields depend on the file's source. Examples: source_metadata.topic (zoom), source_metadata.host_email (zoom), source_metadata.title (gong/grain/iconik), source_metadata.participants.name (grain), source_metadata.parties.email (gong), source_metadata.tags (grain, use ContainsAny), source_metadata.meeting_platform (recall), source_metadata.name (google-drive/dropbox), source_metadata.media_type (iconik), source_metadata.iconik_metadata.<FieldName> (iconik custom metadata-view fields, e.g. source_metadata.iconik_metadata.Keywords with ContainsAny). Paths through arrays of objects match when ANY element matches. ISO datetime fields (zoom start_time, gong started, grain start_datetime, recall started_at, iconik date_created) compare as strings with LessThan/GreaterThan and represent the actual meeting date (or, for iconik, the asset creation date).
      - `path` string, required: JSON path for the field to filter on
      - `operator` 'NotEqual' | 'Equal' | 'LessThan' | 'GreaterThan' | 'ContainsAny' | 'ContainsAll' | 'In' | 'Like', required: Comparison operator to apply
      - `valueText` string: Text value for scalar comparison (used with NotEqual, Equal, LessThan, GreaterThan, Like)
      - `valueTextArray` string[]: Array of values for array comparisons (used with ContainsAny, ContainsAll, In)
  - `threshold` number: Minimum score threshold to filter results. Can be any real number.
  - `group_by_key` 'file': Group results by file. Cannot be used with scope="file" or scope="moment" — grouped moment search is not supported and returns a 400. When specified, results are grouped by file_id.
  - `sort_by` 'score' | 'item_count': Sort order for results. Default: "score". When group_by_key is specified, can also use "item_count" to sort by number of items per group.
  - `search_modalities` string[]: Specifies the type(s) of search to execute. When multiple modalities are specified, a hybrid search is executed that combines results from each modality. Available modalities: - `general_content`: baseline for matching the content of the search item (file/segment) based on visual or spoken content similarity to provided short natural language query string - `speech_lexical`: performs keyword based search (e.g. query of `president` matching `president` or `presidential` strings) and exact match (e.g. specifically find mentions of `"Barack Obama"` or `"Donald Trump"`) against speech content present in search item - `ocr_lexical`: performs keyword based search and exact match against screen text content present in search item - `tag_semantic`: performs basic word semantic similarity search against tag values associated with search items (e.g. `query=animal` expected to match tags with value containing `dog` or `cat`) - `tag_lexical`: performs keyword based search and exact match against tag values associated with search items - `doc_lexical`: performs keyword based search and exact match against file-level documents (generated summaries, metadata-collection docs, and entity-collection docs). Only applicable when search `scope=file`. Only applicable when search `scope=file` or `scope=segment`.
  - `label_filters` string[]: Filter eligible search items by presence of one or more labels in the provided list (otherwise all tags will be considered in search response). Only supported for `tag_semantic` and `tag_lexical` search modalities

## Response `200`

Successful search results

- SearchResponse
  - `id` string, uuid, required: ID of the search response
  - `object` 'search', required: Object type, always 'search'
  - `query` string: The search query that was executed (for text search) or the source image URL/base64 indicator (for face search)
  - `scope` 'file' | 'segment' | 'face' | 'moment', required: The search scope that was used
  - `group_by_key` 'file': The key used for grouping results. Only present when group_by_key was specified in the request and results are grouped.
  - `group_count` integer: Number of groups in the results. Only present when group_by_key is specified.
  - `search_modalities` string[]: Specifies the type(s) of search to execute. When multiple modalities are specified, a hybrid search is executed that combines results from each modality. Available modalities: - `general_content`: baseline for matching the content of the search item (file/segment) based on visual or spoken content similarity to provided short natural language query string - `speech_lexical`: performs keyword based search (e.g. query of `president` matching `president` or `presidential` strings) and exact match (e.g. specifically find mentions of `"Barack Obama"` or `"Donald Trump"`) against speech content present in search item - `ocr_lexical`: performs keyword based search and exact match against screen text content present in search item - `tag_semantic`: performs basic word semantic similarity search against tag values associated with search items (e.g. `query=animal` expected to match tags with value containing `dog` or `cat`) - `tag_lexical`: performs keyword based search and exact match against tag values associated with search items - `doc_lexical`: performs keyword based search and exact match against file-level documents (generated summaries, metadata-collection docs, and entity-collection docs). Only applicable when search `scope=file`. Only applicable when search `scope=file` or `scope=segment`.
  - `results` union[], required: Array of search results ranked by relevance score
    - union
      - FileSearchResult
        - `type` 'file', required: Result type, always 'file'
        - `file_id` string, uuid, required: ID of the file
        - `collection_id` string, uuid, required: ID of the collection containing this file
        - `id` string, uuid, required: ID of the search document
        - `score` number, required: Relevance score (higher is more relevant)
        - `filename` string, nullable: Original filename of the video
        - `summary` string, nullable: Generated summary of the video
        - `generated_title` string, nullable: Generated title of the video
        - `thumbnail_url` string, uri: URL of the thumbnail for the file if available.
        - `tag` SearchTagResponse: The associated tag for the search result if it exists. Only provided for search requests with tag_semantic or tag_lexical search modalities.
          - `id` string, uuid: The ID of the tag
          - `value` string: The value of the tag
          - `label` string: The label of the tag
      - SegmentSearchResult
        - `type` 'segment', required: Result type, always 'segment'
        - `file_id` string, uuid, required: ID of the file
        - `collection_id` string, uuid, required: ID of the collection containing this file
        - `segment_id` string, uuid, required: ID of the segment
        - `id` string, uuid, required: ID of the search document
        - `score` number, required: Relevance score (higher is more relevant)
        - `start_time` number, required: Start time of the segment in seconds
        - `end_time` number, required: End time of the segment in seconds
        - `title` string, nullable: Title associated with the segment
        - `filename` string, nullable: Original filename of the video
        - `visual_description` object[]: Visual descriptions for the segment
          - `text` string: Description of visual content in the segment
          - `start_time` number: Start time of the visual content in seconds
          - `end_time` number: End time of the visual content in seconds
        - `scene_text` object[]: Text detected on screen in the segment
          - `text` string: Text detected on screen
          - `start_time` number: Start time of the text in seconds
          - `end_time` number: End time of the text in seconds
        - `speech` object[]: Speech transcription for the segment
          - `speaker` string: Identified speaker
          - `text` string: Transcribed speech text
          - `start_time` number: Start time of speech in seconds
          - `end_time` number: End time of speech in seconds
        - `thumbnail_url` string, uri: URL of the thumbnail for the segment if available
        - `tag` SearchTagResponse: The associated tag for the search result if it exists. Only provided for search requests with tag_semantic or tag_lexical search modalities.
          - `id` string, uuid: The ID of the tag
          - `value` string: The value of the tag
          - `label` string: The label of the tag
        - `metadata` object: User-provided metadata about the segment, if provided.
        - `keyframes` object[]: Keyframes for the segment
          - `time_in_seconds` number: Time of the keyframe in seconds
          - `thumbnail_url` string, uri: URL of the thumbnail for the keyframe
      - FaceSearchResult
        - `type` 'face', required: Result type, always 'face'
        - `file_id` string, uuid, required: ID of the file containing the matched face
        - `collection_id` string, uuid, required: ID of the collection containing this file
        - `face_id` string, uuid, required: ID of the detected face
        - `frame_id` string, uuid, required: ID of the frame where the face was detected
        - `score` number, required: Similarity score (higher is more similar)
        - `timestamp` number, required: Timestamp of the frame in seconds
        - `face_bounding_box` object
          - `height` number, required: Height of the bounding box (normalized 0-1)
          - `width` number, required: Width of the bounding box (normalized 0-1)
          - `top` number, required: Top position of the bounding box (normalized 0-1)
          - `left` number, required: Left position of the bounding box (normalized 0-1)
        - `thumbnail_url` string: URL of the frame thumbnail
      - MomentSearchResult: A moment search hit (scope='moment'): the full moment record plus provenance and a query-relevance search_score.
        - `moment_id` string, uuid, required
        - `start_time` number, required: Seconds from source start.
        - `end_time` number, required
        - `anchors` object: Declared anchors only; an anchor that was not found is absent, never null.
        - `title` string, required
        - `reason` string, required
        - `speakers` string[]
        - `criterion_score` CriterionScore: The rubric's judgment on its own declared scale.
          - `key` string, required
          - `value` number, required
          - `min` number, required
          - `max` number, required
        - `rank_score` number, required: Normalized ordering within the run; what the default sort uses.
        - `properties` object: Validates against the criterion's moment_schema.
        - `evidence` object
          - `signals` string[]
        - `type` 'moment', required
        - `file_id` string, uuid, required
        - `collection_id` string, uuid, required
        - `job_id` string, uuid, required: The find-moments run that produced this moment
        - `criterion_name` string, required
        - `search_score` number, required: Query relevance for this search only — unrelated to the moment's criterion_score and rank_score
        - `filename` string, nullable, required
      - SegmentGroupResult
        - `type` 'segment_group', required: Result type, always 'segment_group'
        - `matched_items` SegmentSearchResult[], required: Array of segment search results that belong to this file
          - `type` 'segment', required: Result type, always 'segment'
          - `file_id` string, uuid, required: ID of the file
          - `collection_id` string, uuid, required: ID of the collection containing this file
          - `segment_id` string, uuid, required: ID of the segment
          - `id` string, uuid, required: ID of the search document
          - `score` number, required: Relevance score (higher is more relevant)
          - `start_time` number, required: Start time of the segment in seconds
          - `end_time` number, required: End time of the segment in seconds
          - `title` string, nullable: Title associated with the segment
          - `filename` string, nullable: Original filename of the video
          - `visual_description` object[]: Visual descriptions for the segment
            - `text` string: Description of visual content in the segment
            - `start_time` number: Start time of the visual content in seconds
            - `end_time` number: End time of the visual content in seconds
          - `scene_text` object[]: Text detected on screen in the segment
            - `text` string: Text detected on screen
            - `start_time` number: Start time of the text in seconds
            - `end_time` number: End time of the text in seconds
          - `speech` object[]: Speech transcription for the segment
            - `speaker` string: Identified speaker
            - `text` string: Transcribed speech text
            - `start_time` number: Start time of speech in seconds
            - `end_time` number: End time of speech in seconds
          - `thumbnail_url` string, uri: URL of the thumbnail for the segment if available
          - `tag` SearchTagResponse: The associated tag for the search result if it exists. Only provided for search requests with tag_semantic or tag_lexical search modalities.
            - `id` string, uuid: The ID of the tag
            - `value` string: The value of the tag
            - `label` string: The label of the tag
          - `metadata` object: User-provided metadata about the segment, if provided.
          - `keyframes` object[]: Keyframes for the segment
            - `time_in_seconds` number: Time of the keyframe in seconds
            - `thumbnail_url` string, uri: URL of the thumbnail for the keyframe
        - `file_id` string, uuid, required: ID of the file that this group represents
        - `item_count` integer, required: Number of matched items in this group
        - `best_score` number, required: The highest score among all items in this group
      - FaceGroupResult
        - `type` 'face_group', required: Result type, always 'face_group'
        - `matched_items` FaceSearchResult[], required: Array of face search results that belong to this file
          - `type` 'face', required: Result type, always 'face'
          - `file_id` string, uuid, required: ID of the file containing the matched face
          - `collection_id` string, uuid, required: ID of the collection containing this file
          - `face_id` string, uuid, required: ID of the detected face
          - `frame_id` string, uuid, required: ID of the frame where the face was detected
          - `score` number, required: Similarity score (higher is more similar)
          - `timestamp` number, required: Timestamp of the frame in seconds
          - `face_bounding_box` object
            - `height` number, required: Height of the bounding box (normalized 0-1)
            - `width` number, required: Width of the bounding box (normalized 0-1)
            - `top` number, required: Top position of the bounding box (normalized 0-1)
            - `left` number, required: Left position of the bounding box (normalized 0-1)
          - `thumbnail_url` string: URL of the frame thumbnail
        - `file_id` string, uuid, required: ID of the file that this group represents
        - `item_count` integer, required: Number of matched items in this group
        - `best_score` number, required: The highest score among all items in this group
  - `total` integer, required: Total number of results returned. When group_by_key is specified, this represents the total number of items across all groups (not the number of groups).
  - `limit` integer, required: The limit that was applied to the search

## Other responses

- `400`: Invalid request parameters
- `404`: Collection not found
- `500`: An unexpected error occurred on the server

## Changes

- **2026-10-30** `23d3f240819f`: 3 info
  - added the optional property `code` to the response with the `400` status
  - 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-22** `d2a5205fc779`: 1 breaking, 1 warning, 2 info
  - added `#/components/schemas/MomentSearchResult` to the `results/items/` response property `oneOf` list for the response status `200`
  - added the new `moment` enum value to the `scope` response property for the response status `200`
  - added the new optional request property `criterion_name`
  - added the new `moment` enum value to the request property `scope`
- **2026-07-22** `c02e52ec2e28`: 1 warning, 2 info
  - added the new `doc_lexical` enum value to the `search_modalities/items/` response property for the response status `200`
  - added the new optional request property `filter/source_metadata`
  - added the new `doc_lexical` enum value to the request property `search_modalities/items/`
- **2026-03-11** `1d5d6115c0d0`: 4 info
  - the `limit` request property default value `10` was removed
  - the `scope` request property default value `file` was removed
  - the `scope` request property default value `file` was removed
  - the `sort_by` request property default value `score` was removed
- **2026-03-03** `fbee7be59d72`: 1 info
  - added the new optional request property `filter/video_info/items/allOf[subschema #2]/scope`

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