---
title: "Make any-to-video search requests"
method: POST
path: "/search"
tags: ["search"]
---

# Make any-to-video search requests

`POST /search`

Use this endpoint to search for relevant matches in an index using text, media, or a combination of both as your query.

**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`).
- Provide up to 10 images by specifying the following parameters multiple times:
  - `query_media_url`: Publicly accessible URL of your media file.
  - `query_media_file`: Local media file.
**Composed text and media queries**:
- Use the `query_text` parameter for your text query.
- Set `query_media_type` to `image`.
- Provide up to 10 images by specifying the `query_media_url` and `query_media_file` parameters multiple times.

**Entity search** (beta):
- To find a specific person in your videos, enclose the unique identifier of the entity you want to find in the `query_text` parameter.

<Note title="Notes">
- When using images in your search queries (either as media queries or in composed searches), ensure your image files meet the [requirements](/v1.3/docs/concepts/models/marengo#image-file-requirements).
- This endpoint is rate-limited. For details, see the [Rate limits](/v1.3/docs/get-started/rate-limits) page.
</Note>

## Headers

- `x-api-key` string, required

## Response `200`

Successfully performed a search request.

- SearchResults — An object that contains your search results.
  - `data` SearchItem[] — An array that contains your search results. For each match found, the model returns the following fields:
    - `start` number, double — The start time of the matching video clip, expressed in seconds.
    - `end` number, double — The end time of the matching video clip, expressed in seconds.
    - `video_id` string — A string representing the unique identifier of the video. Once the platform indexes a video, it assigns a unique identifier. Note that this is different from the identifier of the video indexing task.
    - `rank` integer — The relevance ranking assigned by the model. Lower numbers indicate higher relevance, starting with 1 for the most relevant result.
    - `thumbnail_url` string — If thumbnail generation has been enabled for this index, the platform returns a string representing the URL of the thumbnail. Note that the URL expires in one hour.
    - `transcription` string — A transcription of the spoken words that are captured in the video.
    - `id` string — A string representing the unique identifier of the video. It only appears when the `group_by=video` parameter is used in the request.
    - `user_metadata` UserMetadata — Metadata that helps you categorize your assets. The object contains user-defined keys and values, where keys are strings and values are one of `string`, `integer`, `float`, or `boolean`. **Example**: ```JSON "user_metadata": { "category": "recentlyAdded", "batchNumber": 5, "rating": 9.3, "needsReview": true } ``` <Note title="Note"> To store other types of data, such as objects or arrays, convert your data into string values before sending it. </Note>
    - `clips` SearchItemClipsItems[] — 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.
      - `start` number, double — The start time of the matching video clip, expressed in seconds.
      - `end` number, double — The end time of the matching video clip, expressed in seconds.
      - `rank` integer — The relevance ranking assigned by the model. Lower numbers indicate higher relevance, starting with 1 for the most relevant result.
      - `thumbnail_url` string — If thumbnail generation has been enabled for this index, the platform returns a string representing the URL of the thumbnail. Note that the URL expires in one hour.
      - `transcription` string — A transcription of the spoken words that are captured in the clip.
      - `video_id` string — A string representing the unique identifier of the video for the corresponding clip.
      - `user_metadata` UserMetadata — Metadata that helps you categorize your assets. The object contains user-defined keys and values, where keys are strings and values are one of `string`, `integer`, `float`, or `boolean`. **Example**: ```JSON "user_metadata": { "category": "recentlyAdded", "batchNumber": 5, "rating": 9.3, "needsReview": true } ``` <Note title="Note"> To store other types of data, such as objects or arrays, convert your data into string values before sending it. </Note>
  - `page_info` SearchResultsPageInfo — An object that provides information about pagination.
    - `limit_per_page` integer — The maximum number of items on each page. When grouping by video, this field represents the maximum number of videos per page. Otherwise, it represents the maximum number of video clips per page.
    - `page_expires_at` string — A string representing the date and time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), that the page expires.
    - `total_results` integer — The total number of results. When grouping by video, this field represents the total number of video clips matching your query. Otherwise , this field represents the total number of videos.
    - `total_inner_matches` integer — When grouping by video, the platform return this field that shows the total number of video clips matching your query.
    - `next_page_token` string — The unique identifier of the next page.
  - `search_pool` SearchPool — An object that contains details about the index you queried.
    - `total_count` integer — The number of videos in the index you queried.
    - `total_duration` number, double — The total duration of the videos.
    - `index_id` string — The unique identifier of the index.

## Other responses

- `400` — The request has failed.
- `429` — If the rate limit is reached, the platform returns an `HTTP 429 - Too many requests` error response. The response body is empty.

---

[API](https://skmtc.net/twelvelabs/apis/twelvelabs-api.md) · [All operations](https://skmtc.net/twelvelabs/apis/twelvelabs-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/twelvelabs/twelvelabs-api/revisions/fd9d80e384a8/schema)