---
title: "Video Search"
method: POST
path: "/api/v1/search/video"
tags: ["search-video > searchVideo"]
---

# Video Search

`POST /api/v1/search/video`

Executes a semantic video search using a natural language text query (e.g., 'person walking in park' or 'cityscape at sunset') within a specified dataset (dataset_id). The text query is encoded into an embedding using the dataset's configured encoder (e.g., Perception Encoder or other vision-language embedding models for visual modalities, or Qwen or other text encoders for audio transcript modality), then searched against video content embeddings using vector similarity. The search behavior is controlled by the modality parameter: 'video' (default) searches video-level embeddings for overall video similarity, 'shot' searches shot-level embeddings to find videos with similar scenes, 'image' searches frame-level embeddings to find videos with similar individual frames, and 'audio_speech_to_text' searches transcript text embeddings for spoken content. All modalities return one result per video, surfacing the most relevant composite slice (shot or scene) and a preview frame. Results can be filtered using optional metadata filters and include the composite slice with start/end timestamps, frame numbers, relevance scores, and video metadata.

## Headers

- `Authorization` string, required

## Request body

- SearchVideoVideoSearchRequest — Request schema for video search endpoint.
  - `dataset_id` string, uuid, required — The unique identifier for the dataset
  - `text_query` string, required — The natural language search string
  - `metadata_filters` SearchVideoMetadataFilters — Metadata filters for video search.
    - `filters` SearchVideoMetadataFiltersFiltersItems[], required
      - union
        - SearchVideoBooleanEqualsClause
          - `key` string, required
          - `operator` '==', required
          - `value` boolean, required
        - SearchVideoEqualsClause
          - `key` string, required
          - `operator` '==', required
          - `value` string, required
        - SearchVideoNotEqualsClause
          - `key` string, required
          - `operator` '!=', required
          - `value` string, required
        - SearchVideoDateTimeRangeInclusiveClause
          - `key` string, required
          - `start_utc_epoch` number, double, required
          - `end_utc_epoch` number, double, required
          - `operator` 'DateTimeRangeInclusive', required
  - `offset` integer — Starting index to return (default 0)
  - `limit` integer — Max number of items to return(default 60, max 1000)
  - `modality` 'video' | 'shot' | 'image' | 'audio_speech_to_text' | 'capped-shot-segment'
  - `skip_moderation` boolean — Skip content moderation if enabled
  - `moderation_score_type` 'probability' | 'level' — Score type returned by the moderation service. - PROBABILITY: Scores in range 0-1 (uses BGE Reranker model) - LEVEL: Scores in range 0-5 (uses OpenAI model)
  - `ignore_keyframes` boolean — Whether to ignore keyframes

## Response `200`

Successful Response

- SearchVideoVideoSearchResponse — Response schema for video search endpoint.
  - `results` SearchVideoVideoSearchResult[], required — List of video search results
    - `dataset_id` string, uuid, required
    - `text_query` string, required
    - `video_id` string, uuid, required
    - `source_path` string, required
    - `video_score` number, double, nullable
    - `metadata` union
      - SearchVideoVideoMetadata — Metadata associated with a video shot.
        - `data` object
      - object
    - `top_composite_slice` SearchVideoVideoCompositeSlice — Response schema for video composite details.
      - `id` string, uuid, required
      - `index` integer, nullable
      - `start_frame_num` integer, nullable
      - `end_frame_num` integer, nullable
      - `start_time_ms` integer, nullable
      - `end_time_ms` integer, nullable
      - `composite_id` string, uuid, nullable
      - `composite_type` string — Type of composite
    - `top_keyframe` SearchVideoVideoKeyframe — Response schema for video keyframe details.
      - `id` string, uuid, required
      - `frame_time_ms` integer, nullable
    - `moderation_score` number, double, nullable

## Other responses

- `422` — Validation Error

## Changes

- **2026-08-22** `1223758be9ba` — 1 breaking
  - the `text_query` request property's minLength was increased from `0` to `2`

[Change history](https://skmtc.dev/coactive/apis/api-reference/changes/api/v1/search/video/post.md)

---

[API](https://skmtc.dev/coactive/apis/api-reference.md) · [All operations](https://skmtc.dev/coactive/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/coactive/api-reference/revisions/1223758be9ba/schema)