> This page is for version v1.3 (default). > For other versions, use one of these documentation indexes: > - v1.3 (default): https://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://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 `SearchClient` class provides methods to perform search requests. [**Related quickstart notebook**](https://colab.research.google.com/github/twelvelabs-io/twelvelabs-developer-experience/blob/main/quickstarts/TwelveLabs_Quickstart_Search.ipynb) # 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 `query_text` parameter to specify your query. Media queries: * Set the `query_media_type` parameter to the corresponding media type (example: `image`). * For a single image, specify one of the following parameters: * `query_media_url`: Publicly accessible URL of your media file. * `query_media_file`: Local media file. If you specify both, `query_media_url` takes precedence. * For multiple images (up to 10), specify one of the following parameters: * `query_media_urls`: Publicly accessible URLs of your media files. * `query_media_files`: Local media files. Composed text and media queries: * Use the `query_text` parameter for your text query. * Set `query_media_type` to `image`. * Specify your images using `query_media_url`, `query_media_file`, `query_media_urls`, or `query_media_files`. > **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 `query_text` 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`** ```python Function signature def query( self, *, index_id: str, search_options: typing.List[SearchCreateRequestSearchOptionsItem], query_media_type: typing.Optional[typing.Literal["image"]] = OMIT, query_media_url: typing.Optional[str] = OMIT, query_media_file: typing.Optional[core.File] = OMIT, query_media_urls: typing.Optional[typing.List[str]] = OMIT, query_media_files: typing.Optional[typing.List[core.File]] = OMIT, query_text: typing.Optional[str] = OMIT, group_by: typing.Optional[SearchCreateRequestGroupBy] = OMIT, operator: typing.Optional[SearchCreateRequestOperator] = OMIT, page_limit: typing.Optional[int] = OMIT, filter: typing.Optional[str] = OMIT, request_options: typing.Optional[RequestOptions] = None, ) -> SyncPager[SearchItem] ``` **`Text search`** ```python Text search from twelvelabs import TwelveLabs response = client.search.query( index_id="", search_options=["visual", "audio"], query_text="", group_by="video", operator="or", filter='{"category": "nature"}', page_limit=5, ) print("Search Results:") for item in response: if item.id and item.clips: # Grouped by video print(f"Video ID: {item.id}") for clip in item.clips: print(" Clip:") print(f" Start: {clip.start}") print(f" End: {clip.end}") print(f" Video ID: {clip.video_id}") print(f" Rank: {clip.rank}") print(f" Thumbnail URL: {clip.thumbnail_url}") else: # Individual clips print(f" Start: {item.start}") print(f" End: {item.end}") print(f" Video ID: {item.video_id}") print(f" Rank: {item.rank}") print(f" Thumbnail URL: {item.thumbnail_url}") if item.transcription: print(f" Transcription: {item.transcription}") ``` **`Multiple images`** ```python Multiple images from twelvelabs import TwelveLabs client = TwelveLabs(api_key="") response = client.search.query( index_id="", search_options=["visual"], query_media_type="image", query_media_urls=[ "", "", ], ) print("Search Results:") for item in response: print(f" Start: {item.start}") print(f" End: {item.end}") print(f" Video ID: {item.video_id}") print(f" Rank: {item.rank}") ``` **`Multiple images and text`** ```python Multiple images and text from twelvelabs import TwelveLabs client = TwelveLabs(api_key="") response = client.search.query( index_id="", search_options=["visual"], query_media_type="image", query_media_urls=[ "", "", ], query_text="", ) print("Search Results:") for item in response: print(f" Start: {item.start}") print(f" End: {item.end}") print(f" Video ID: {item.video_id}") print(f" Rank: {item.rank}") ``` ### Parameters | Name | Type | Required | Description | | ----------------------- | --------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `index_id` | `str` | Yes | The unique identifier of the index to search. | | `search_options` | `List` `[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. | | `transcription_options` | `typing.Optional` `[typing.List` `[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"]`. | | | | | | | `query_text` | `str` | No | The text query to search for. This parameter is required for text queries. Marengo supports up to 500 tokens per query. | | `query_media_type` | `Literal["image"]` | 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 `query_text` together with this parameter when you want to perform a composed image+text search. | | `query_media_file` | `core.File` | No | A local media file to use as a query. This parameter is required for media queries if `query_media_url` is not provided. | | `query_media_url` | `str` | No | The publicly accessible URL of a media file to use as a query. This parameter is required for media queries if `query_media_file` is not provided. | | `query_media_files` | `List[core.File]` | No | A list of opened file objects in binary read mode to use as a query. You can provide up to 10 images in total. | | `query_media_urls` | `List[str]` | No | A list of publicly accessible URLs of media files to use as a query. You can provide up to 10 images in total. | | `group_by` | `SearchCreateRequestGroupBy` | No | Use this parameter to group or ungroup items in a response. Values: `video`, `clip`. Default: `clip`. | | `operator` | `SearchCreateRequestOperator` | No | Logical operator for combining search options. Values: `or`, `and`. Default: `or`. | | `page_limit` | `int` | No | The number of items to return on each page. Max: 50. | | `filter` | `str` | No | A stringified object to filter search results based on video metadata or custom fields. | | `include_user_metadata` | `bool` | No | Specifies whether to include user-defined metadata in the search results. | | `request_options` | `RequestOptions` | No | Request-specific configuration. | ### Return value Returns a `SyncPager[SearchItem]` object that allows you to iterate through the paginated search results. The `SyncPager[T]` class contains the following properties and methods: | Name | Type | Description | | -------------- | ------------------------------------------------ | ---------------------------------------------------------------------- | | `items` | `Optional[List[T]]` | A list containing the current page of items. Can be `None`. | | `has_next` | `bool` | Indicates whether there is a next page to load. | | `get_next` | `Optional[Callable[[], Optional[SyncPager[T]]]]` | A callable function that retrieves the next page. Can be `None`. | | `response` | `Optional[BaseHttpResponse]` | The HTTP response object. Can be `None`. | | `next_page()` | `Optional[SyncPager[T]]` | Calls `get_next()` if available and returns the next page object. | | `__iter__()` | `Iterator[T]` | Allows iteration through all items across all pages using `for` loops. | | `iter_pages()` | `Iterator[SyncPager[T]]` | Allows iteration through page objects themselves. | The `SearchItem` class contains the following properties: | Name | Type | Description | | --------------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `start` | `Optional[float]` | The start time of the clip in seconds. | | `end` | `Optional[float]` | The end time of the clip in seconds. | | `video_id` | `Optional[str]` | The unique identifier of the video. Once the platform indexes a video, it assigns a unique identifier. | | `rank` | `Optional[int]` | The relevance ranking assigned by the model. Lower numbers indicate higher relevance, starting with 1 for the most relevant result. | | `thumbnail_url` | `Optional[str]` | The URL of the thumbnail image for the clip. | | `transcription` | `Optional[str]` | A transcription of the spoken words that are captured in the video. | | `id` | `Optional[str]` | The unique identifier of the video. Only appears when the `group_by=video` parameter is used in the request. | | `user_metadata` | `Optional[typing.Dict[str, typing.Optional[UserMetadataValue]]]` | User-defined metadata associated with the video. | | `clips` | `Optional[List[SearchItemClipsItem]]` | An array that contains detailed information about the clips that match your query. The platform returns this array only when the `group_by` parameter is set to `video` in the request. | The `SearchItemClipsItem` class contains the following properties: | Name | Type | Description | | --------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `start` | `Optional[float]` | The start time of the clip in seconds. | | `end` | `Optional[float]` | The end time of the clip in seconds. | | `rank` | `Optional[int]` | The relevance ranking assigned by the model. Lower numbers indicate higher relevance, starting with 1 for the most relevant result. | | `thumbnail_url` | `Optional[str]` | The URL of the thumbnail image for the clip. | | `transcription` | `Optional[str]` | A transcription of the spoken words that are captured in the clip. | | `video_id` | `Optional[str]` | The unique identifier of the video for the corresponding clip. | | `user_metadata` | `Optional[typing.Dict[str, typing.Optional[UserMetadataValue]]]` | 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 guide * [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.