> 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 > Perform search requests. The `SearchWrapper` class provides methods to perform search requests. # Methods ## Make a search request **Description**: This method performs a search across a specific index using text, media, or a combination of both as your query and returns a paginated iterator of search results. Text queries: * Use the `queryText` parameter to specify your query. Media queries: * Set the `queryMediaType` parameter to the corresponding media type (example: `image`). * For a single image, specify one of the following parameters: * `queryMediaUrl`: Publicly accessible URL of your media file. * `queryMediaFile`: Local media file. If you specify both, `queryMediaUrl` takes precedence. * For multiple images (up to 10), specify one of the following parameters: * `queryMediaUrls`: Publicly accessible URLs of your media files. * `queryMediaFiles`: Local media files. Composed text and media queries: * Use the `queryText` parameter for your text query. * Set `queryMediaType` to `image`. * Specify your images using `queryMediaUrl`, `queryMediaFile`, `queryMediaUrls`, or `queryMediaFiles`. > **Note** > > When using images in your search queries (either as media queries or in composed searches), ensure your images meet the [requirements](/v1.3/docs/concepts/models/marengo/marengo-3-0#image-file-requirements). Entity search: * To find a specific person in your videos, enclose the unique identifier of the entity you want to find in the `queryText` parameter. For instructions on setting up and using this feature, see the [Entity search](/v1.3/docs/guides/search/entity-search) page. > **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 query( request: SearchWrapper.QueryRequest, requestOptions?: Search.RequestOptions ): Promise> ``` **`Text search`** ```javascript Text search import { TwelveLabs } from "twelvelabs-js"; const response = await client.search.query({ indexId: "", searchOptions: ["visual", "audio"], queryText: "", groupBy: "video", operator: "or", filter: '{"category": "nature"}', pageLimit: 5, }); console.log("Search Results:"); for await (const item of response) { if (item.id && item.clips) { // Grouped by video console.log(`Video ID: ${item.id}`); for (const clip of item.clips) { console.log(" Clip:"); console.log(` Start: ${clip.start}`); console.log(` End: ${clip.end}`); console.log(` Video ID: ${clip.videoId}`); console.log(` Rank: ${clip.rank}`); console.log(` Thumbnail URL: ${clip.thumbnailUrl}`); } } else { // Individual clips console.log(` Start: ${item.start}`); console.log(` End: ${item.end}`); console.log(` Video ID: ${item.videoId}`); console.log(` Rank: ${item.rank}`); console.log(` Thumbnail URL: ${item.thumbnailUrl}`); if (item.transcription) { console.log(` Transcription: ${item.transcription}`); } } } ``` **`Multiple images`** ```javascript Multiple images import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const response = await client.search.query({ indexId: "", searchOptions: ["visual"], queryMediaType: "image", queryMediaUrls: [ "", "", ], }); console.log("Search Results:"); for await (const item of response) { console.log(` Start: ${item.start}`); console.log(` End: ${item.end}`); console.log(` Video ID: ${item.videoId}`); console.log(` Rank: ${item.rank}`); } ``` **`Multiple images and text`** ```javascript Multiple images and text import { TwelveLabs } from "twelvelabs-js"; const client = new TwelveLabs({ apiKey: "" }); const response = await client.search.query({ indexId: "", searchOptions: ["visual"], queryMediaType: "image", queryMediaUrls: [ "", "", ], queryText: "", }); console.log("Search Results:"); for await (const item of response) { console.log(` Start: ${item.start}`); console.log(` End: ${item.end}`); console.log(` Video ID: ${item.videoId}`); console.log(` Rank: ${item.rank}`); } ``` ### Parameters | Name | Type | Required | Description | | :--------------- | :------------------------------------- | :------- | :------------------------------ | | `request` | \[`TwelvelabsApi.SearchCreateRequest`] | Yes | The search request parameters. | | `requestOptions` | \[`Search.RequestOptions`] | No | Request-specific configuration. | The `SearchCreateRequest` interface defines the parameters for performing a search: | Name | Type | Required | Description | | ---------------------- | -------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `indexId` | `string` | Yes | The unique identifier of the index to search. | | `searchOptions` | `TwelvelabsApi.` `SearchCreateRequestSearchOptionsItem[]` | Yes | Specifies the modalities the video understanding model uses to find relevant information. Available options: - `visual`: Searches visual content. - `audio`: Searches non-speech audio. - `transcription`: Spoken words You can specify multiple search options in conjunction with the `operator` parameter to broaden or narrow your search. For guidance, see the [Search options](/v1.3/docs/concepts/modalities#search-options) section. | | `transcriptionOptions` | `TwelvelabsApi.` `SearchCreateRequestTranscriptionOptionsItem[]` | No | Specifies how the platform matches your text query with the words spoken in the video. This parameter applies only when the `search_options` parameter contains the `transcription` value. Available options: - `lexical`: Exact word matching - `semantic`: Meaning-based matching For details on when to use each option, see the [Transcription options](/v1.3/docs/concepts/modalities#transcription-options) section. **Default**: `["lexical", "semantic"]`. | | | | | | | `queryText` | `string` | No | The text query to search for. This parameter is required for text queries. Marengo supports up to 500 tokens per query. | | `queryMediaType` | `TwelvelabsApi.SearchCreateRequestQueryMediaType` | No | The type of media you wish to use. This parameter is required for media queries. For example, to perform an image-based search, set this parameter to `image`. Use `queryText` together with this parameter when you want to perform a composed image+text search. | | `queryMediaFile` | `File \| fs.ReadStream \| Blob \| (File \| fs.ReadStream \| Blob)[]` | No | A local media file to use as a query. Pass a single file or an array of up to 10 files. This parameter is required for media queries if `queryMediaUrl` is not provided. | | `queryMediaUrl` | `string` | No | The publicly accessible URL of a media file to use as a query. This parameter is required for media queries if `queryMediaFile` is not provided. | | `queryMediaFiles` | `(File \| fs.ReadStream \| Blob)[]` | No | A list of local media files to use as a query. You can provide up to 10 images in total. | | `queryMediaUrls` | `string[]` | No | A list of publicly accessible URLs of media files to use as a query. You can provide up to 10 images in total. | | `groupBy` | `TwelvelabsApi.SearchCreateRequestGroupBy` | No | Use this parameter to group or ungroup items in a response. Values: `video`, `clip`. Default: `clip`. | | `operator` | `TwelvelabsApi.SearchCreateRequestOperator` | No | Logical operator for combining search options. Values: `or`, `and`. Default: `or`. | | `pageLimit` | `number` | No | The number of items to return on each page. Max: 50. | | `filter` | `string` | No | A stringified object to filter search results based on video metadata or custom fields. | | `includeUserMetadata` | `boolean` | No | Specifies whether to include user-defined metadata in the search results. | ### Return value Returns a `Promise` that resolves to a `Page` object that implements `AsyncIterable`, allowing you to iterate through the paginated search results. The `Page` class contains the following properties and methods: | Name | Type | Description | | ---------------------- | ------------------ | ---------------------------------------------------------------------------- | | `data` | `T[]` | An array containing the current page of items. | | `getNextPage()` | `Promise` | Retrieves the next page and returns the updated `Page` object. | | `hasNextPage()` | `boolean` | Returns whether there is a next page to load. | | `Symbol.asyncIterator` | `AsyncIterator` | Allows iteration through all items across all pages using `for await` loops. | The `SearchItem` interface contains the following properties: | Name | Type | Description | | --------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `start` | `number` | The start time of the clip in seconds. | | `end` | `number` | The end time of the clip in seconds. | | `videoId` | `string` | The unique identifier of the video. Once the platform indexes a video, it assigns a unique identifier. | | `rank` | `number` | The relevance ranking assigned by the model. Lower numbers indicate higher relevance, starting with 1 for the most relevant result. | | `thumbnailUrl` | `string` | The URL of the thumbnail image for the clip. | | `transcription` | `string` | A transcription of the spoken words that are captured in the video. | | `id` | `string` | The unique identifier of the video. Only appears when the `groupBy=video` parameter is used in the request. | | `userMetadata` | `Record` | User-defined metadata associated with the video. | | `clips` | `SearchItemClipsItem[]` | An array that contains detailed information about the clips that match your query. The platform returns this array only when the `groupBy` parameter is set to `video` in the request. | The `SearchItemClipsItem` interface contains the following properties: | Name | Type | Description | | --------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `start` | `number` | The start time of the clip in seconds. | | `end` | `number` | The end time of the clip in seconds. | | `rank` | `number` | The relevance ranking assigned by the model. Lower numbers indicate higher relevance, starting with 1 for the most relevant result. | | `thumbnailUrl` | `string` | The URL of the thumbnail image for the clip. | | `transcription` | `string` | A transcription of the spoken words that are captured in the clip. | | `videoId` | `string` | The unique identifier of the video for the corresponding clip. | | `userMetadata` | `Record` | User-defined metadata associated with the video. | ### API Reference [Any-to-video search](/v1.3/api-reference/any-to-video-search/make-search-request). ### Related guides * [Search](/v1.3/docs/guides/search) * [Filtering](/v1.3/docs/guides/search/filtering) * [Grouping](/v1.3/docs/guides/search/grouping) # Error codes This section lists the most common error messages you may encounter while performing search requests. * `search_option_not_supported` * Search option `{search_option}` is not supported for index `{index_id}`. Please use one of the following search options: `{supported_search_option}`. * `search_option_combination_not_supported` * Search option `{search_option}` is not supported with `{other_combination}`. * `search_filter_invalid` * Filter used in search is invalid. Please use the valid filter syntax by following filtering documentation. * `search_page_token_expired` * The token that identifies the page to be retrieved is expired or invalid. You must make a new search request. Token: `{next_page_token}`. * `index_not_supported_for_search`: * You can only perform search requests on indexes with an engine from the Marengo family enabled. For a list of general errors that apply to all endpoints, see the [Error codes](/v1.3/api-reference/error-codes) page.