For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Sample appsIntegrationsDiscordPlaygroundDevEx repo
GuidesSDK ReferenceAPI Reference
GuidesSDK ReferenceAPI Reference
  • Python SDK
    • The TwelveLabs class
    • Manage indexes
    • Upload content
    • Index content
    • Manage videos
    • Manage entities
    • Search
    • Create embeddings v2
    • Create embeddings v1
    • Analyze and segment videos
  • Node.js SDK
    • The TwelveLabs class
    • Manage indexes
    • Upload content
    • Index content
    • Manage videos
    • Manage entities
    • Search
    • Create embeddings v2
    • Create embeddings v1
    • Analyze and segment videos
LogoLogo
Sample appsIntegrationsDiscordPlaygroundDevEx repo
On this page
  • Methods
  • Make a search request
  • Parameters
  • Return value
  • API Reference
  • Related guide
  • Error codes
Python SDK

Search

Was this page helpful?
Previous

Create embeddings v2

Next
Built with

The SearchClient class provides methods to perform search requests.

Related quickstart notebook

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 image files meet the 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 page.

Note

This method is rate-limited. For details, see the Rate limits page.

Function signature and example:

1def query(
2    self,
3    *,
4    index_id: str,
5    search_options: typing.List[SearchCreateRequestSearchOptionsItem],
6    query_media_type: typing.Optional[typing.Literal["image"]] = OMIT,
7    query_media_url: typing.Optional[str] = OMIT,
8    query_media_file: typing.Optional[core.File] = OMIT,
9    query_media_urls: typing.Optional[typing.List[str]] = OMIT,
10    query_media_files: typing.Optional[typing.List[core.File]] = OMIT,
11    query_text: typing.Optional[str] = OMIT,
12    group_by: typing.Optional[SearchCreateRequestGroupBy] = OMIT,
13    operator: typing.Optional[SearchCreateRequestOperator] = OMIT,
14    page_limit: typing.Optional[int] = OMIT,
15    filter: typing.Optional[str] = OMIT,
16    request_options: typing.Optional[RequestOptions] = None,
17) -> SyncPager[SearchItem]

Parameters

NameTypeRequiredDescription
index_idstrYesThe unique identifier of the index to search.
search_optionsList
[SearchCreateRequestSearchOptionsItem]		YesSpecifies 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 section.
transcription_optionstyping.Optional
[typing.List
[SearchCreateRequestTranscriptionOptionsItem]]		NoSpecifies 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 section.
Default: ["lexical", "semantic"].
query_textstrNoThe text query to search for. This parameter is required for text queries. Marengo supports up to 500 tokens per query.
query_media_typeLiteral["image"]NoThe 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_filecore.FileNoA local media file to use as a query. This parameter is required for media queries if query_media_url is not provided.
query_media_urlstrNoThe 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_filesList[core.File]NoA 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_urlsList[str]NoA list of publicly accessible URLs of media files to use as a query. You can provide up to 10 images in total.
group_bySearchCreateRequestGroupByNoUse this parameter to group or ungroup items in a response. Values: video, clip. Default: clip.
operatorSearchCreateRequestOperatorNoLogical operator for combining search options. Values: or, and. Default: or.
page_limitintNoThe number of items to return on each page. Max: 50.
filterstrNoA stringified object to filter search results based on video metadata or custom fields.
include_user_metadataboolNoSpecifies whether to include user-defined metadata in the search results.
request_optionsRequestOptionsNoRequest-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:

NameTypeDescription
itemsOptional[List[T]]A list containing the current page of items. Can be None.
has_nextboolIndicates whether there is a next page to load.
get_nextOptional[Callable[[], Optional[SyncPager[T]]]]A callable function that retrieves the next page. Can be None.
responseOptional[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:

NameTypeDescription
startOptional[float]The start time of the clip in seconds.
endOptional[float]The end time of the clip in seconds.
video_idOptional[str]The unique identifier of the video. Once the platform indexes a video, it assigns a unique identifier.
rankOptional[int]The relevance ranking assigned by the model. Lower numbers indicate higher relevance, starting with 1 for the most relevant result.
thumbnail_urlOptional[str]The URL of the thumbnail image for the clip.
transcriptionOptional[str]A transcription of the spoken words that are captured in the video.
idOptional[str]The unique identifier of the video. Only appears when the group_by=video parameter is used in the request.
user_metadataOptional[typing.Dict[str, typing.Optional[typing.Any]]]User-defined metadata associated with the video.
clipsOptional[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:

NameTypeDescription
startOptional[float]The start time of the clip in seconds.
endOptional[float]The end time of the clip in seconds.
rankOptional[int]The relevance ranking assigned by the model. Lower numbers indicate higher relevance, starting with 1 for the most relevant result.
thumbnail_urlOptional[str]The URL of the thumbnail image for the clip.
transcriptionOptional[str]A transcription of the spoken words that are captured in the clip.
video_idOptional[str]The unique identifier of the video for the corresponding clip.
user_metadataOptional[typing.Dict[str, typing.Optional[typing.Any]]]User-defined metadata associated with the video.

API Reference

Any-to-video search.

Related guide

  • Search
  • Filtering
  • 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 page.