API ReferenceText-to-video search

Make a combined search request

Use this method to search for relevant matches in an index using combined queries.

For clarity, the combined search feature is documented in this section. However, note that the /search endpoint supports all the features of the /combined-search endpoint.

This method returns the first page of results. To retrieve the subsequent pages, you must call the GET method of the /combined-search/{page-token} endpoint, passing it the unique identifier of the page you want to retrieve.

Notes
  • TwelveLabs Inc. has disabled calling this method from this page to avoid confusion and recommends you invoke it using one of the available SKDs. See the Use combined queries page for details.
  • This endpoint is rate-limited. For details, see the Rate limits page.
  • When you use pagination, you will not be charged for retrieving subsequent pages of results.

Headers

x-api-keystringRequired

Request

This endpoint expects an object.
index_idstringRequired

The unique identifier of the index to search.

search_optionslist of stringsRequired

An array that specifies the sources of information the platform uses when performing a search. For details, see the Search options page.

Note

The search options you specify must be a subset of the engine options used when you created the index.

queryobjectRequired

Use the query parameter to build combined queries.

For details about building combined queries, see the Combined queries page.

conversation_optionenumOptionalDefaults to semantic

Specifies the type of match the platform will perform. The following values are supported: semantic and exact_match. For details, see the Conversation option page.

Default: semantic

Allowed values:
adjust_confidence_leveldoubleOptional

This parameter specifies the strictness of the thresholds for assigning the high, medium, or low confidence levels to search results. If you use a lower value, the thresholds become more relaxed, and more search results will be classified as having high, medium, or low confidence levels. You can use this parameter to include a broader range of potentially relevant video clips, even if some results might be less precise.

Min: 0 Max: 1 Default: 0.5

filterobjectOptional

Use this parameter to filter your search results by metadata.

For string fields, the filter parameter returns only the results that equal the value you specify. The following example filters on the videos whose title is “Animal Encounters part 1”: "title": "Animal Encounters part 1".

For numeric fields, the filter parameter returns the results that match based on the arithmetic comparison. The following example filters on the videos whose height is greater than or equal to 400 and less than or equal to 500: "height": { "gte": 400, "lte": 500 }.

To enable filtering by custom fields:

  1. Add metadata to your video by calling the the PUT method of the /indexes/:index-id/videos/:video-id endpoint
  2. Use the custom fields as filter criteria in your queries. For example, to return only videos where a custom field named needsReview of type boolean is true, use: "needs_review": true.
page_limitdoubleOptionalDefaults to 10

The number of items to return on each page.

Default: 10 Max: 50

thresholdenumOptionalDefaults to low

Use this parameter to filter on the level of confidence that the results match your query.

Default: low

Allowed values:

Response

Successfully performed a search request.

datalist of objectsOptional

An array of objects that contains your search results.

page_infoobjectOptional

An object that provides information about pagination.

search_poolobjectOptional

An object that contains details about the index you queried.

Errors