> 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 Node.js SDK. The `KnowledgeStores` 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 `searchOptions` parameter to choose how the platform matches videos. By default, each result is an individual match: a video clip or an image. Set the `groupBy` 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`** ```javascript Function signature search( knowledgeStoreId: string, request: TwelvelabsApi.SearchKnowledgeStoreRequest, requestOptions?: KnowledgeStores.RequestOptions ): Promise ``` **`Node.js example`** ```javascript Node.js example import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const response = await client.knowledgeStores.search("", { query: { text: "A person cooking pasta" }, searchOptions: { video: { modalities: ["visual", "audio"], }, }, // filter: { assetType: { in: ["video"] } }, // groupBy: "none", // pageSize: 10, // pageToken: "", // includeMetadata: true, }); for (const hit of response.data) { console.log(`Rank: ${hit.rank} Item: ${hit.itemId} Type: ${hit.assetType}`); } ``` ### Parameters | Name | Type | Required | Description | | :----------------- | :-------------------------------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `knowledgeStoreId` | `string` | Yes | The unique identifier of the knowledge store. | | `query` | `KnowledgeStore` `SearchQuery` | Yes | The search query. | | `filter` | `SearchKnowledge` `StoreFilter` | No | Narrows results to specific items in the knowledge store. Omit the filter to search all items. | | `searchOptions` | `SearchKnowledge` `StoreOptions` | No | Specifies how videos are matched. If you provide options in the `searchOptions.video` field when the `filter.assetType` 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. | | `groupBy` | `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`. | | `pageSize` | `number` | No | The maximum number of results per page. A result is one entry in the `data` array. With the `groupBy` 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`. | | `pageToken` | `string` | 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 `nextPageToken` 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). | | `includeMetadata` | `boolean` | 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. | | `requestOptions` | `KnowledgeStores.` `RequestOptions` | No | Per-call SDK settings such as timeout, retries, and headers. For all fields, see [Request options](/v1.3/sdk-reference/node-js/the-twelve-labs-class#request-options). | The `KnowledgeStoreSearchQuery` object contains the following property: | Name | Type | Required | Description | | :----- | :------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------- | | `text` | `string` | 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` object 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 `userMetadata`, `enrichment`, `createdAt`, 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 `itemId` field. The `assetType` 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` object describes. It contains the following properties: | Name | Type | Required | Description | | :------------- | :------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `assetType` | `AssetTypeFilter` | No | Narrows results by type of item. Provide exactly one operator: `eq` (a string) to match one type, or `in` (an array) to match any of the listed types. Values: `video`, `image`. | | `itemId` | `ItemIdFilter` | No | Narrows results to specific items. Provide exactly one operator: `eq` (a string) to match one item, or `in` (an array) to match any of the listed items. | | `userMetadata` | `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 `itemMetadata` 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 `string`, `number`, or `boolean`): 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` (an array of `string`, `number`, or `boolean` 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` | `EnrichmentFilter` | No | Narrows results by enrichment values. The platform extracts these values as the enrichment configuration of the knowledge store defines (the `ingestionConfig.enrichmentConfig` 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 `string`, `number`, or `boolean`): 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` (an array of `string`, `number`, or `boolean` 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`. | | `createdAt` | `CreatedAtFilter` | No | Narrows results by the creation time of the item. Use `gte` (a `Date`) to set the earliest time and `lte` (a `Date`) 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/node-js/knowledge-store-items#create-a-knowledge-store-item) method of `client.knowledgeStoreItems`. 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/node-js/knowledge-store-items#retrieve-a-knowledge-store-item) method of `client.knowledgeStoreItems`. The time is in the `createdAt` field. | | `location` | `GeoCircleFilter` | No | Narrows results to items captured within a circle. | | `tags` | `TagFilter` | No | Narrows results to the moments and ranges that matching tags mark on video items. | The `GeoCircleFilter` object narrows results to items captured within a circle. An item matches when the GPS coordinates embedded in its source media are within `radiusMeters` 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/node-js/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` | `number` | Yes | The latitude of the center, in decimal degrees. The value must be between -90 and 90. | | `longitude` | `number` | Yes | The longitude of the center, in decimal degrees. The value must be between -180 and 180. | | `radiusMeters` | `number` | Yes | The radius of the circle, in meters. The value must be greater than 0 and at most 20,037,508. | The `TagFilter` object 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 `groupBy` 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 `assetType` 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.knowledgeStoreItemTags`. It contains the following property: | Name | Type | Required | Description | | :--------- | :-------------------------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `metadata` | `Record` | 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` (an array 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` object contains the following property: | Name | Type | Required | Description | | :------ | :------------------- | :------- | :--------------------------------------------------------------------------------------------------- | | `video` | `VideoSearchOptions` | No | Options that control how videos are matched. By default, videos are matched on their visual content. | The `VideoSearchOptions` object contains the following properties: | Name | Type | Required | Description | | :----------- | :------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `modalities` | `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` object contains the following properties: | Name | Type | Description | | :----------------------- | :------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data` | `SearchKnowledge` `StoreHit[]` | Search results, ordered by relevance. | | `nextPageToken` | `string` | Pagination token for the next page. Pass this value as the `pageToken` parameter in your next request to retrieve more results. Absent when no more pages exist. | | `effectiveSearchOptions` | `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 `assetType` field: | Name | Type | Description | | :---------- | :----------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `assetType` | `"video" \| "image"` | The type of item that matched. | | `rank` | `number` | The relevance ranking assigned by the model. | | `itemId` | `string` | The unique identifier of the matching item. | | `metadata` | `VideoSearch` `ItemMetadata` or `ImageSearch` `ItemMetadata` | Metadata attached to the item. Returned when you set the `includeMetadata` parameter to `true`. A `VideoSearchItemMetadata` object for video results, an `ImageSearchItemMetadata` object for image results. | | `matches` | `VideoMatch[]` | The matching clips within the video. Present only when `assetType` is `video`. | The `VideoSearchItemMetadata` object contains metadata attached to a video knowledge store item in search results. It contains the following properties: | Name | Type | Description | | :------- | :---------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `system` | `VideoSearch` `SystemMetadata` | System-generated metadata for the source video. | | `user` | `Record` | The custom metadata of the source asset. The `metadata` field of the knowledge store item contains the same metadata. | | `item` | `Record` | 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` object contains metadata attached to an image knowledge store item in search results. It contains the following properties: | Name | Type | Description | | :------- | :---------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `system` | `ImageSearch` `SystemMetadata` | System-generated metadata for the source image. | | `user` | `Record` | The custom metadata of the source asset. The `metadata` field of the knowledge store item contains the same metadata. | | `item` | `Record` | 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` object contains system-generated metadata for a video item in search results. It contains the following properties: | Name | Type | Description | | :--------- | :------- | :------------------------------------ | | `duration` | `number` | The duration of the video in seconds. | | `width` | `number` | The width of the video in pixels. | | `height` | `number` | The height of the video in pixels. | | `size` | `number` | The file size of the video in bytes. | The `ImageSearchSystemMetadata` object contains system-generated metadata for an image item in search results. It contains the following properties: | Name | Type | Description | | :------- | :------- | :----------------------------------- | | `width` | `number` | The width of the image in pixels. | | `height` | `number` | The height of the image in pixels. | | `size` | `number` | The file size of the image in bytes. | The `VideoMatch` object contains the following properties: | Name | Type | Description | | :-------------- | :------------------------- | :------------------------------------------------------------------------------------------------------------------------------ | | `startSec` | `number` | The clip start offset, in seconds, within the source video. | | `endSec` | `number` | The clip end offset, in seconds, within the source video. | | `modalities` | `VideoSearch` `Modality[]` | 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. | ### API Reference [Search a knowledge store](/v1.3/api-reference/knowledge-store-search/search).