---
title: "Search a knowledge store"
method: POST
path: "/knowledge-stores/{knowledge_store_id}/search"
tags: ["knowledgeStores"]
---

# Search a knowledge store

`POST /knowledge-stores/{knowledge_store_id}/search`

This method searches a knowledge store using natural language and returns matching video clips and images ranked by relevance.

Provide your natural-language query in the `query.text` field. Use the `filter` parameter to choose which items to search: by type of item (the `asset_type` field) or by specific items (the `item_id` field). Use the optional `search_options` parameter to control how videos are matched (by visual content, audio, or both). If you omit it, videos are matched on their visual content. Images are always matched on their visual content.

By default, each result is an individual match: a video clip or an image. Set the `group_by` parameter to `item` to group clips under their parent item.

<Note title="Note">
This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page.
</Note>

## Path parameters

- `knowledge_store_id` string, required

## Headers

- `x-api-key` string, required

## Request body

- SearchKnowledgeStoreRequest — Request body for searching a knowledge store. To paginate, set the `page_token` parameter to the `next_page_token` field returned in the previous response and send the request again. The token identifies the original search, so any search fields you send are ignored.
  - `query` KnowledgeStoreSearchQuery, required — The search query.
    - `text` string, required — Describe what you're searching for in natural language (Examples: `A person cooking pasta` or `aerial shots of a city at night`).
  - `filter` SearchKnowledgeStoreFilter — Narrows results to specific items in the knowledge store. Filter by type of item (the `asset_type` field) or by specific identifiers (the `item_id` field). Use `eq` to match a single value or `in` to match any value in a list. When you specify multiple fields, the platform applies all conditions together. Examples: ```json { "asset_type": { "eq": "video" } } ``` ```json { "asset_type": { "in": [ "video" ] }, "item_id": { "in": [ "ksi_069e9870-3c4d-7abc-9012-3456789abcde" ] } } ``` Omit the filter to search all items.
    - `asset_type` AssetTypeFilter — Narrows results by type of item. Provide exactly one operator: `eq` to match one type, or `in` to match any of the listed types.
      - `eq` 'video' | 'image' — The type of item in the knowledge store.
      - `in` KnowledgeStoreItemAssetType[] — Match items whose `asset_type` is one of these values.
    - `item_id` ItemIdFilter — Narrows results to specific items. Provide exactly one operator: `eq` to match one item, or `in` to match any of the listed items.
      - `eq` string — Match the item with this identifier.
      - `in` string[] — Match any item whose identifier is in this list.
  - `search_options` SearchKnowledgeStoreOptions — Specifies how videos are matched. Videos are the only type of item with configurable options, set in the `search_options.video` field. Images are always matched on their visual content and have no options to configure. To choose which types of items to search, use the `filter.asset_type` field. Providing options in the `search_options.video` field when the `filter.asset_type` field excludes videos returns a `400` error. If you omit this field, videos are matched on their visual content.
    - `video` VideoSearchOptions — Options that control how videos are matched. By default, videos are matched on their visual content.
      - `modalities` VideoSearchModality[], required — The video modalities used for searching. Available options: - `visual`: Searches visual content. - `audio`: Searches audio content, including speech and non-speech sounds. You can combine multiple modalities to broaden your search. For example, to search both visual content and audio, set the `modalities` parameter to `["visual", "audio"]`. For guidance, see [Search options](/v1.3/docs/concepts/modalities#search-options).
  - `group_by` 'none' | 'item' — Controls how the platform groups matches in the response. - `none`: Returns individual matches ordered by relevance. - `item`: Groups matches under their parent item. **Default**: `none`.
  - `page_size` integer — The maximum number of results per page. A result is one entry in the `data` array. With the `group_by` parameter set to its default of `none`, each result is an individual match: a video clip or an image. When set to `item`, each result is one item: a video with all its matching clips, or an image. **Default**: `10`. **Max**: `50`.
  - `page_token` string — Pagination token used to retrieve the next page of results. Omit it on the first request. To fetch the next page, set it to the `next_page_token` field returned in the previous response and send the request again. A malformed or unrecognized token returns a `400` error. A token that has expired returns a `410` error (make a new search request to obtain a fresh page token).
  - `include_metadata` boolean — Set to `true` to include metadata in each result. Each result includes a `metadata` object with a `system` field (platform-derived file properties such as duration and resolution) and a `user` field (metadata you attached to the item).

## Response `200`

The search completed successfully.

- SearchKnowledgeStoreResponse — The search results. Each entry in the `data` array includes an `asset_type` field that indicates the type of item.
  - `data` SearchKnowledgeStoreHit[], required — Search results, ordered by relevance.
    - union — A single result in the search response. The fields present depend on the `asset_type` field.
      - object — A search result for a video.
        - `asset_type` 'video', required — Discriminator value: video
        - `rank` integer, required — The relevance position of this result, starting at 1. When `group_by` is `item`, videos are ordered by their most relevant clip.
        - `item_id` string, required — The unique identifier of the knowledge store item.
        - `metadata` VideoSearchItemMetadata — Metadata attached to a video knowledge store item in search results.
          - `system` VideoSearchSystemMetadata — System-generated media metadata for a video item in search results.
            - `duration` number, double — The duration of the video in seconds.
            - `width` integer — The width of the video in pixels.
            - `height` integer — The height of the video in pixels.
            - `size` integer — The file size of the video in bytes.
          - `user` UserMetadata — Metadata that helps you categorize your assets. The object contains user-defined keys and values, where keys are strings and values are one of `string`, `integer`, `float`, or `boolean`. **Example**: ```JSON "user_metadata": { "category": "recentlyAdded", "batchNumber": 5, "rating": 9.3, "needsReview": true } ``` <Note title="Note"> To store other types of data, such as objects or arrays, convert your data into string values before sending it. </Note>
        - `matches` VideoMatch[], required — Matching clips from this video, ordered by relevance. - When `group_by` is `none`: Contains one entry — the matching clip. - When `group_by` is `item`: Contains all matching clips from this video, with the best match first.
          - `start_sec` number, double, required — The clip start offset, in seconds, within the source video.
          - `end_sec` number, double, required — The clip end offset, in seconds, within the source video.
          - `modalities` VideoSearchModality[], required — The modalities that matched in this clip.
          - `transcription` string — The spoken words in the clip. Returned when spoken-word data is available for the clip, regardless of which modalities matched.
      - object — A search result for an image. An image matches as a whole object and has no time range.
        - `asset_type` 'image', required — Discriminator value: image
        - `rank` integer, required — The relevance position of this result, starting at 1.
        - `item_id` string, required — The unique identifier of the knowledge store item.
        - `metadata` ImageSearchItemMetadata — Metadata attached to an image knowledge store item in search results.
          - `system` ImageSearchSystemMetadata — System-generated media metadata for an image item in search results.
            - `width` integer — The width of the image in pixels.
            - `height` integer — The height of the image in pixels.
            - `size` integer — The file size of the image in bytes.
          - `user` UserMetadata — Metadata that helps you categorize your assets. The object contains user-defined keys and values, where keys are strings and values are one of `string`, `integer`, `float`, or `boolean`. **Example**: ```JSON "user_metadata": { "category": "recentlyAdded", "batchNumber": 5, "rating": 9.3, "needsReview": true } ``` <Note title="Note"> To store other types of data, such as objects or arrays, convert your data into string values before sending it. </Note>
  - `next_page_token` string — The unique identifier of the next page.
  - `effective_search_options` SearchKnowledgeStoreOptions, required — Specifies how videos are matched. Videos are the only type of item with configurable options, set in the `search_options.video` field. Images are always matched on their visual content and have no options to configure. To choose which types of items to search, use the `filter.asset_type` field. Providing options in the `search_options.video` field when the `filter.asset_type` field excludes videos returns a `400` error. If you omit this field, videos are matched on their visual content.
    - `video` VideoSearchOptions — Options that control how videos are matched. By default, videos are matched on their visual content.
      - `modalities` VideoSearchModality[], required — The video modalities used for searching. Available options: - `visual`: Searches visual content. - `audio`: Searches audio content, including speech and non-speech sounds. You can combine multiple modalities to broaden your search. For example, to search both visual content and audio, set the `modalities` parameter to `["visual", "audio"]`. For guidance, see [Search options](/v1.3/docs/concepts/modalities#search-options).

## Other responses

- `400` — The request has failed.
- `404` — The specified resource does not exist.
- `410` — The page token has expired. Page tokens are valid for a limited time; make a new search request to obtain a fresh first page and a new token.
- `429` — If the rate limit is reached, the platform returns an `HTTP 429 - Too many requests` error response. The response body is empty.

---

[API](https://skmtc.net/twelvelabs/apis/twelvelabs-api.md) · [All operations](https://skmtc.net/twelvelabs/apis/twelvelabs-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/twelvelabs/twelvelabs-api/revisions/fd9d80e384a8/schema)