> 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 `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. Provide exactly one operator: `eq` (a `str`) to match one item, or `in_` (a list) to match any of the listed items. | | `user_metadata` | `Optional` `[UserMetadataFilter]` | No | Narrows results by custom metadata. Map each key to a `MetadataValueFilter` object with exactly one of the `eq` or `in_` operators. 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 `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).