---
title: "Create a deep search"
method: POST
path: "/deepSearch"
tags: ["Deep Search"]
---

# Create a deep search

`POST /deepSearch`

## Request

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

Create a new deep search over one or more collections. Deep search uses agentic retrieval and LLM summarization to find specific moments across your video data.

The search can be processed synchronously (default), streamed via SSE, or run in the background.

## Request body

- CreateDeepSearchRequest
  - `knowledge_base` union, required: Knowledge base configuration. Determines which content to search. Three source modes are supported: - `collections`: Search within specific collections - `files`: Search specific files by URL or file ID (uses default index) - `default`: Search all default-indexed files for the account
    - DeepSearchKBCollections: Search within specific collections.
      - `source` 'collections', required: Source mode identifier.
      - `collections` string[], required: Collection IDs to search. Collections must be of type rich-transcripts, media-descriptions, metadata, or entities. With an explicit scope, every collection must be searchable at it: metadata collections only have file-level docs and require scope='file'; entities collections follow their extraction level — file-level extraction (enable_video_level_entities or enable_metadata_mode) requires scope='file', segment-level extraction (enable_segment_level_entities) requires scope='segment'. When scope is omitted (auto), collection types can be mixed freely: each collection is searched at the scopes its documents support.
      - `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)
    - DeepSearchKBFiles: Search specific files by URL or file ID. Files must have been described or added to a collection to be searchable.
      - `source` 'files', required: Source mode identifier.
      - `files` string[], required: File references to search. Can be file UUIDs, cloudglue URIs (`cloudglue://files/...`), data connector URLs, or HTTP URLs.
    - DeepSearchKBDefault: Search all default-indexed files for the account. Includes any file that has been described (with `use_in_default_index: true`) or added to a collection.
      - `source` 'default', required: Source mode identifier.
  - `query` string, required: The search query.
  - `scope` 'segment' | 'file': The scope of results to return. 'segment' returns individual segments, 'file' returns file-level results — explicit values behave exactly as before, and every collection in the knowledge base must be searchable at the requested scope (metadata and file-level entities collections require 'file'; segment-level entities collections require 'segment'). Omit for auto: the search planner picks a scope per search plan, each collection is searched at the scopes its documents support, and results from both scopes are fused — so a knowledge base can mix collection types (e.g. rich-transcripts + metadata + entities) without a scope.
  - `limit` integer: Maximum number of results to return. Actual count may be lower when exclude_weak_results is enabled.
  - `exclude_weak_results` boolean: When true, removes results tagged as weak matches by the synthesis LLM.
  - `include` string[]: Additional fields to include in the response. 'search_queries' includes the intermediate search query plan.
  - `stream` boolean: Stream the response via SSE. Mutually exclusive with background.
  - `background` boolean: Process in the background. Returns immediately with status 'in_progress'. Mutually exclusive with stream.

## Response `200`

Deep search created successfully

- DeepSearch
  - `id` string, uuid: Deep search ID
  - `object` 'deep_search': Object type identifier
  - `status` 'in_progress' | 'completed' | 'failed' | 'cancelled': Current status of the deep search
  - `created_at` number: Unix timestamp of when the deep search was created
  - `query` string: The original search query
  - `scope` 'segment' | 'file', nullable: The scope the caller requested. Null when the request omitted scope (auto: the planner chose scopes per search plan, so results may mix segment and file types).
  - `text` string, nullable: LLM-generated synthesis text summarizing the results
  - `results` DeepSearchResult[], nullable: Array of search results
    - `type` 'segment' | 'file': The type of result
    - `id` string, uuid: Result ID
    - `file_id` string, uuid: The file ID this result belongs to
    - `collection_id` string, uuid: The collection ID this result belongs to. Present when using `collections` source; omitted for `files` and `default` sources.
    - `score` number: Relevance score
    - `context` string: LLM-generated context explaining why this result is relevant
    - `segment_id` string, uuid: Segment ID (present when type is 'segment')
    - `start_time` number: Start time in seconds (present when type is 'segment')
    - `end_time` number: End time in seconds (present when type is 'segment')
    - `title` string, nullable: Segment title
    - `filename` string, nullable: Original filename
    - `thumbnail_url` string, nullable: URL to a thumbnail image
    - `metadata` object, nullable: Additional metadata
    - `summary` string, nullable: File summary (present when type is 'file')
    - `generated_title` string, nullable: Generated title (present when type is 'file')
  - `total` integer: Total number of results
  - `limit` integer: Maximum number of results requested
  - `search_queries` DeepSearchSearchQueryPlan[], nullable: Intermediate search query plans (included when requested via include=['search_queries'])
    - `query` string: The search query
    - `search_modalities` string[]: Modalities used for this search
    - `scope` string: Search scope
    - `filter` object, nullable: Optional filter applied
    - `result_count` integer: Number of results returned for this query
  - `usage` DeepSearchUsage
    - `input_tokens` integer: Number of input tokens used
    - `output_tokens` integer: Number of output tokens used
    - `total_tokens` integer: Total number of tokens used
    - `search_calls` integer: Number of search calls made
  - `error` object, nullable: Error details if the deep search failed
    - `message` string
    - `type` string
    - `code` string

## Other responses

- `400`: Invalid request parameters
- `403`: Usage limit reached (monthly or daily chat completions) — `code: usage_limit_reached`
- `404`: Collection not found
- `500`: An unexpected error occurred on the server

## Changes

- **2026-10-30** `23d3f240819f`: 4 info
  - added the non-success response with the status `403`
  - 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-12** `725b9736a231`: 1 breaking, 1 info
  - the response property `scope` became nullable for the status `200`
  - the `scope` request property default value `segment` was removed
- **2026-07-22** `c02e52ec2e28`: 1 info
  - added the new optional request property `knowledge_base/oneOf[#/components/schemas/DeepSearchKBCollections]/filter/allOf[#/components/schemas/SearchFilter]/source_metadata`
- **2026-03-16** `9dc639e1d66c`: 1 info
  - endpoint added

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