> This page is for version v1.3 (default). > For other versions, use one of these documentation indexes: > - v1.3 (default): https://beta.docs.twelvelabs.io/v1.3/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://beta.docs.twelvelabs.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://beta.docs.twelvelabs.io/_mcp/server. # Search a knowledge store > Search across the items in a knowledge store with the Python SDK. The `KnowledgeStoresClient` class provides the `search` method to search across the items in a knowledge store using natural language. # Methods ## Search a knowledge store **Description**: This method searches a knowledge store using natural language and returns matching video clips and images ranked by relevance. Use the `query.text` field to specify your natural-language query. Use the `filter` parameter to choose which items to search. Use the `search_options` parameter to choose how the platform matches videos. 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** > > This method is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page. **Function signature and example**: **`Function signature`** ```python Function signature def search( self, knowledge_store_id: str, *, query: KnowledgeStoreSearchQuery, filter: typing.Optional[SearchKnowledgeStoreFilter] = OMIT, search_options: typing.Optional[SearchKnowledgeStoreOptions] = OMIT, group_by: typing.Optional[SearchKnowledgeStoreRequestGroupBy] = OMIT, page_size: typing.Optional[int] = OMIT, page_token: typing.Optional[str] = OMIT, include_metadata: typing.Optional[bool] = OMIT, request_options: typing.Optional[RequestOptions] = None, ) -> SearchKnowledgeStoreResponse: ``` **`Python example`** ```python Python example from twelvelabs import ( TwelveLabs, KnowledgeStoreSearchQuery, SearchKnowledgeStoreFilter, AssetTypeFilter, SearchKnowledgeStoreOptions, VideoSearchOptions, ) client = TwelveLabs(api_key="") response = client.knowledge_stores.search( knowledge_store_id="", query=KnowledgeStoreSearchQuery(text="A person cooking pasta"), search_options=SearchKnowledgeStoreOptions( video=VideoSearchOptions( modalities=["visual", "audio"], ), ), # filter=SearchKnowledgeStoreFilter( # asset_type=AssetTypeFilter(in_=["video"]), # ), # group_by="none", # page_size=10, # page_token="", # include_metadata=True, ) for hit in response.data: print(f"Rank: {hit.rank} Item: {hit.item_id} Type: {hit.asset_type}") ``` ### Parameters | Name | Type | Required | Description | | :------------------- | :------------------------------------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledge_store_id` | `str` | Yes | The unique identifier of the knowledge store. | | `query` | `KnowledgeStore` `SearchQuery` | Yes | The search query. | | `filter` | `typing.` `Optional` `[SearchKnowledge` `StoreFilter]` | No | Narrows results to specific items in the knowledge store. Omit the filter to search all items. | | `search_options` | `typing.` `Optional` `[SearchKnowledge` `StoreOptions]` | No | Specifies how videos are matched. If you provide options in the `search_options.video` field when the `filter.asset_type` field excludes videos, the platform returns a `400` error. If you omit this field, videos are matched on their visual content. Images are always matched on their visual content and have no options to configure. | | `group_by` | `typing.` `Optional` `[SearchKnowledge` `StoreRequestGroupBy]` | No | 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` | `typing.` `Optional[int]` | No | 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` | `typing.` `Optional[str]` | No | 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. If a token is malformed or unrecognized, the platform returns a `400` error. If a token has expired, the platform returns a `410` error (make a new search request to obtain a fresh page token). | | `include_metadata` | `typing.` `Optional[bool]` | No | Set to `true` to include metadata in each result. Each result includes a `metadata` object with these fields: - `system`: System-generated metadata, such as duration and resolution. - `user`: The custom metadata of the source asset. - `item`: The custom metadata of the knowledge store item. | | `request_options` | `typing.` `Optional` `[RequestOptions]` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/python/the-twelve-labs-class#request-options). | The `KnowledgeStoreSearchQuery` class contains the following property: | Name | Type | Required | Description | | :----- | :---- | :------- | :-------------------------------------------------------------------------------------------------------------------------------- | | `text` | `str` | Yes | Describe what you're searching for in natural language (Examples: `A person cooking pasta` or `aerial shots of a city at night`). | The `SearchKnowledgeStoreFilter` class narrows results to specific items in the knowledge store. Omit the filter to search all items. An item must match all of the fields that you specify. The `tags` field also limits which clips of an item the search returns. When you use any of the `item_collection_id`, `user_metadata`, `enrichment`, `created_at`, or `location` fields, the platform counts the items that match those conditions together. If more than 10,000 items match, the platform returns a `422` error with the `metadata_filter_too_broad` code. To reduce the count, add conditions or use the `item_id` field. The `asset_type` field does not reduce the count. When you use the `tags` field, the platform does not count items, and this limit does not apply. It counts the matching tags instead, as the `TagFilter` class describes. It contains the following properties: | Name | Type | Required | Description | | :------------------- | :------------------------------------ | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `asset_type` | `Optional` `[AssetTypeFilter]` | No | Narrows results by type of item. Provide exactly one operator: `eq` (a `KnowledgeStoreItemAssetType`) to match one type, or `in_` (a list) to match any of the listed types. Values: `video`, `image`. | | `item_id` | `Optional` `[ItemIdFilter]` | No | Narrows results to specific items. Use `eq` to match one item or `in_` to match any item in a list. Use `nin` to exclude every clip or image belonging to 1 to 20,000 listed items. You cannot use `eq` and `in_` together. You can use `nin` on its own or with either `eq` or `in_`. If an item is listed in `nin` and selected by `eq` or `in_`, the platform excludes it. | | `item_collection_id` | `Optional` `[ItemCollectionIdFilter]` | No | Narrows results to the items in item collections. Provide exactly one operator: `eq` (a `str`) to match the items in one item collection, or `in_` (a list of item collections) to match the items in any of them. If an item collection has no items, the search returns no results. The search also returns no results when no item matches the other fields in the `filter` object. If an item collection is not in the knowledge store, the platform returns a `404` error with the `resource_not_exists` code. If the identifier of an item collection is not valid, the platform returns a `400` error with the `parameter_invalid` code. | | `user_metadata` | `Optional` `[UserMetadataFilter]` | No | Narrows results by custom metadata. Map each key to a `UserMetadataValueFilter` object with `eq`, `in_`, or inclusive `gte`/`lte` bounds. You can specify 1 to 50 keys. An item must match all of the keys that you specify. A key matches the custom metadata of the source asset (the `metadata` field of the knowledge store item) and the custom metadata of the knowledge store item (the `item_metadata` field). An item matches a key when the value matches in either field. For the names of these fields in search results, see the [Custom metadata field names](/v1.3/api-reference/knowledge-store-items/the-knowledge-store-item-object#custom-metadata-field-names) section on **The knowledge store item object** page. `eq` (a `str`, `int`, `float`, or `bool`): Match items that have this value for the key. The value must have the same type as the value that the item has for the key. For example, the number `2026` does not match the string `"2026"`. If the item has a list for the key, the item matches when the list contains the value. `in_` (a list of `str`, `int`, `float`, or `bool` values): Match items that have any of these values for the key. You can specify 1 to 100 values. Each value follows the rules for the `eq` operator. For example, `["tutorial", "guide"]` matches items that have the value `tutorial` or `guide`. | | `enrichment` | `Optional` `[EnrichmentFilter]` | No | Narrows results by enrichment values. The platform extracts these values as the enrichment configuration of the knowledge store defines (the `ingestion_config.enrichment_config` field). Map each top-level property that the enrichment configuration defines to a `MetadataValueFilter` object with exactly one of the `eq` or `in_` operators. You can specify 1 to 50 keys. If you specify a key that the enrichment configuration does not define, the platform returns a `400` error. The `granularity` keyword of a property sets how often the platform extracts its value. The keyword also sets which items the key matches: - `video`: One value for each video. The key matches video items only. - `image`: One value for each image. The key matches image items only. - `shot`: One value for each shot of a video. A shot is a continuous part of a video between two scene changes. The key matches video items only. If you specify more than one `shot` key, one shot must have all of the values. For example, a filter with the keys `topic` and `sentiment` at the `shot` granularity matches a video only when one shot has both values. An item must match all of the keys that you specify. A filter with a `video` key and an `image` key matches no items, because an item is a video or an image. Use the filter to choose which items to search. The search can return any clip of a matching item, including clips that do not match the filter. `eq` (a `str`, `int`, `float`, or `bool`): Match items that have this value for the key. The value must have the same type as the value that the item has for the key. For example, the number `2026` does not match the string `"2026"`. If the item has a list for the key, the item matches when the list contains the value. `in_` (a list of `str`, `int`, `float`, or `bool` values): Match items that have any of these values for the key. You can specify 1 to 100 values. Each value follows the rules for the `eq` operator. For example, `["tutorial", "guide"]` matches items that have the value `tutorial` or `guide`. | | `created_at` | `Optional` `[CreatedAtFilter]` | No | Narrows results by the creation time of the item. Use `gte` (a `datetime`) to set the earliest time and `lte` (a `datetime`) to set the latest time. You can use one or both. When you use both, the `gte` time must be equal to or earlier than the `lte` time. The creation time is the time when you create the item with the [`create`](/v1.3/sdk-reference/python/knowledge-store-items#create-a-knowledge-store-item) method of `client.knowledge_store_items`. It is not the time when the item reaches the `ready` status. To read the creation time of an item, use the [`retrieve`](/v1.3/sdk-reference/python/knowledge-store-items#retrieve-a-knowledge-store-item) method of `client.knowledge_store_items`. The time is in the `created_at` field. | | `location` | `Optional` `[GeoCircleFilter]` | No | Narrows results to items captured within a circle. | | `tags` | `Optional` `[TagFilter]` | No | Narrows results to the moments and ranges that matching tags mark on video items. | The `ItemIdFilter` class contains the following properties. You cannot use `eq` and `in_` together. You can use `nin` on its own or with either `eq` or `in_`. If an item is listed in `nin` and selected by `eq` or `in_`, the platform excludes it. | Name | Type | Required | Description | | :---- | :-------------------- | :------- | :--------------------------------------------------------------------------------------- | | `eq` | `Optional[str]` | No | Match the item with this identifier. | | `in_` | `Optional[List[str]]` | No | Match any item with an identifier in this non-empty list. | | `nin` | `Optional[List[str]]` | No | Exclude every clip or image belonging to these items. You can list 1 to 20,000 item IDs. | The `UserMetadataValueFilter` class matches one custom metadata key. Use exactly one of `eq` or `in_`, or a range with `gte`, `lte`, or both. Do not combine `eq` or `in_` with range bounds. Both range bounds must be numbers or both must be RFC 3339 timestamps with a timezone, and `gte` must not exceed `lte`. A single stored value must satisfy both bounds. Numeric ranges match numeric scalars, excluding numeric strings and booleans. Date ranges compare times with their timezone offsets. A timestamp must include a time and a timezone (`Z` or an offset such as `+09:00`). A date without a time, such as `2026-09-29`, or a timestamp without a timezone returns a `400` error. Missing keys, malformed date values, nulls, and arrays in stored metadata do not match a range. | Name | Type | Required | Description | | :---- | :------------------------------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------- | | `eq` | `Optional[MetadataScalarValue]` | No | Match a string, number, or boolean with the same JSON type as the stored value. A stored list matches when it contains the value. | | `in_` | `Optional[List[MetadataScalarValue]]` | No | Match any of 1 to 100 values. Each value follows the rules for `eq`. | | `gte` | `Optional[MetadataRangeBound]` | No | Inclusive lower bound. Use a number or an RFC 3339 timestamp with a timezone, such as `2026-09-29T00:00:00Z` or `2026-09-29T09:00:00+09:00`. | | `lte` | `Optional[MetadataRangeBound]` | No | Inclusive upper bound. Use a number or an RFC 3339 timestamp with a timezone, such as `2026-09-29T00:00:00Z` or `2026-09-29T09:00:00+09:00`. | The `GeoCircleFilter` class narrows results to items captured within a circle. An item matches when the GPS coordinates embedded in its source media are within `radius_meters` of the center, measured as [great-circle distance](https://en.wikipedia.org/wiki/Great-circle_distance). Items with no coordinates never match. To read the GPS coordinates of the source media, use the [`retrieve`](/v1.3/sdk-reference/python/manage-assets#retrieve-an-asset) method of `client.assets`. The coordinates are the `geospatial_latitude` and `geospatial_longitude` fields of the `technical_metadata` object. It contains the following properties: | Name | Type | Required | Description | | :-------------- | :------ | :------- | :-------------------------------------------------------------------------------------------- | | `latitude` | `float` | Yes | The latitude of the center, in decimal degrees. The value must be between -90 and 90. | | `longitude` | `float` | Yes | The longitude of the center, in decimal degrees. The value must be between -180 and 180. | | `radius_meters` | `float` | Yes | The radius of the circle, in meters. The value must be greater than 0 and at most 20,037,508. | The `TagFilter` class narrows results to the moments and ranges that matching tags mark on video items. A tag matches when its `tag_metadata` field matches the `metadata` field. Only video items have tags, so images do not appear in the results. The search returns only the clips within a matching tag: * For a tag on a range, a clip matches when it lies entirely within the range. A clip that extends past either end of the range does not appear in the results. * For a tag on a single moment, a clip matches when it contains that moment. A clip within more than one matching tag appears once. With the `group_by` parameter set to `item`, each item groups only its clips within matching tags. When you specify other fields of the filter, a tag counts only when its item matches every other field. The `asset_type` field does not reduce the count. If more than 100 tags match, the platform returns a `422` error with the `metadata_filter_too_broad` code. To tag a moment or a range of a video item, use the `create` method of `client.knowledge_store_item_tags`. It contains the following property: | Name | Type | Required | Description | | :--------- | :------------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `metadata` | `Dict` `[str, Metadata` `ValueFilter]` | Yes | The metadata to match against the `tag_metadata` field of each tag. Map each key to a `MetadataValueFilter` with exactly one operator: `eq` to match one value, or `in_` (a list of 1 to 100 values) to match any of the listed values. Specify 1 to 50 keys. When you specify more than one key, every key must match on the same tag. A value is a string, a number, or a boolean. The platform matches it with the JSON type the tag stores, so `2026` does not match a tag that stores `"2026"`. A key that stores a list matches when the list contains the value. | The `SearchKnowledgeStoreOptions` class contains the following property: | Name | Type | Required | Description | | :------ | :-------------------------------- | :------- | :--------------------------------------------------------------------------------------------------- | | `video` | `Optional` `[VideoSearchOptions]` | No | Options that control how videos are matched. By default, videos are matched on their visual content. | The `VideoSearchOptions` class contains the following properties: | Name | Type | Required | Description | | :----------- | :-------------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `modalities` | `List` `[VideoSearch` `Modality]` | Yes | The video modalities used for searching. - `visual`: Searches visual content. - `audio`: Searches audio content, including speech and non-speech sounds. You can combine multiple modalities to broaden your search. For guidance, see [Search options](/v1.3/docs/concepts/modalities#search-options). | ### Return value Returns a `SearchKnowledgeStoreResponse` object. The `SearchKnowledgeStoreResponse` class contains the following properties: | Name | Type | Description | | :------------------------- | :------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data` | `List` `[SearchKnowledge` `StoreHit]` | Search results, ordered by relevance. | | `next_page_token` | `Optional[str]` | Pagination token for the next page. Pass this value as the `page_token` parameter in your next request to retrieve more results. Absent when no more pages exist. | | `effective_search_options` | `SearchKnowledge` `StoreOptions` | The video options applied to this search, including any defaults. When the search includes videos, this object contains a `video` field with the modalities used. When the search is limited to images, this object is empty. | Each entry in the `data` array is a `SearchKnowledgeStoreHit`. The fields present depend on the `asset_type` field: | Name | Type | Description | | :----------- | :------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `asset_type` | `Literal` `["video",` `"image"]` | The type of item that matched. | | `rank` | `int` | The relevance ranking assigned by the model. | | `item_id` | `str` | The unique identifier of the matching item. | | `metadata` | `Optional` `[VideoSearch` `ItemMetadata] or` `Optional` `[ImageSearch` `ItemMetadata]` | Metadata attached to the item. Returned when you set the `include_metadata` parameter to `true`. A `VideoSearchItemMetadata` object for video results, an `ImageSearchItemMetadata` object for image results. | | `matches` | `List` `[VideoMatch]` | The matching clips within the video. Present only when `asset_type` is `video`. | The `VideoSearchItemMetadata` class contains metadata attached to a video knowledge store item in search results. It contains the following properties: | Name | Type | Description | | :------- | :------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `system` | `Optional` `[VideoSearch` `SystemMetadata]` | System-generated metadata for the source video. | | `user` | `Optional[Dict` `[str, KnowledgeStore` `MetadataValue]]` | The custom metadata of the source asset. The `metadata` field of the knowledge store item contains the same metadata. | | `item` | `Optional[Dict` `[str, KnowledgeStore` `MetadataValue]]` | The custom metadata of the knowledge store item. It is separate from the custom metadata of the source asset. A change to the custom metadata of the source asset does not change this field. The same key can have different values in the `user` field and in the `item` field. The `item_metadata` field of the knowledge store item contains the same metadata. This field is absent when no item metadata has been set. | The `ImageSearchItemMetadata` class contains metadata attached to an image knowledge store item in search results. It contains the following properties: | Name | Type | Description | | :------- | :------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `system` | `Optional` `[ImageSearch` `SystemMetadata]` | System-generated metadata for the source image. | | `user` | `Optional[Dict` `[str, KnowledgeStore` `MetadataValue]]` | The custom metadata of the source asset. The `metadata` field of the knowledge store item contains the same metadata. | | `item` | `Optional[Dict` `[str, KnowledgeStore` `MetadataValue]]` | The custom metadata of the knowledge store item. It is separate from the custom metadata of the source asset. A change to the custom metadata of the source asset does not change this field. The same key can have different values in the `user` field and in the `item` field. The `item_metadata` field of the knowledge store item contains the same metadata. This field is absent when no item metadata has been set. | The `VideoSearchSystemMetadata` class contains system-generated metadata for a video item in search results. It contains the following properties: | Name | Type | Description | | :--------- | :---------------- | :------------------------------------ | | `duration` | `Optional[float]` | The duration of the video in seconds. | | `width` | `Optional[int]` | The width of the video in pixels. | | `height` | `Optional[int]` | The height of the video in pixels. | | `size` | `Optional[int]` | The file size of the video in bytes. | The `ImageSearchSystemMetadata` class contains system-generated metadata for an image item in search results. It contains the following properties: | Name | Type | Description | | :------- | :-------------- | :----------------------------------- | | `width` | `Optional[int]` | The width of the image in pixels. | | `height` | `Optional[int]` | The height of the image in pixels. | | `size` | `Optional[int]` | The file size of the image in bytes. | The `VideoMatch` class contains the following properties: | Name | Type | Description | | :-------------- | :-------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | | `start_sec` | `float` | The clip start offset, in seconds, within the source video. | | `end_sec` | `float` | The clip end offset, in seconds, within the source video. | | `modalities` | `List` `[VideoSearch` `Modality]` | The modalities that matched in this clip. | | `transcription` | `Optional[str]` | The spoken words in the clip. Returned when spoken-word data is available for the clip, regardless of which modalities matched. | ### API Reference [Search a knowledge store](/v1.3/api-reference/knowledge-store-search/search).