> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.twelvelabs.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://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. 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** > > 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 a `system` field (platform-derived file properties such as duration and resolution) and a `user` field (metadata you attached to the 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. Filter by type of item or by specific identifiers. When you specify both fields, the platform applies all conditions together. 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. | 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` `[KnowledgeStore` `SearchItemMetadata]` | Metadata for the item. Returned when the `include_metadata` parameter is set to `true`. | | `matches` | `List` `[VideoMatch]` | The matching clips within the video. Present only when `asset_type` is `video`. | 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).