> 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.

# Retrieve a specific page of search results

GET https://api.twelvelabs.io/v1.3/search/{page-token}

Use this endpoint to retrieve a specific page of search results.

When you use pagination, you will not be charged for retrieving subsequent pages of results.

Reference: https://docs.twelvelabs.io/api-reference/any-to-video-search/retrieve-page

## Authentication

- `x-api-key` header (required) — Your API key. You can find your API key on the API Keys page.

## Request

### Path parameters

- `page-token` (string, required) — A token that identifies the page to retrieve.

### Query parameters

- `include_user_metadata` (boolean, optional) — Specifies whether to include user-defined metadata in the search results.

## Response

### 200

Successfully retrieved the specified page of search results.

- `data` (list of SearchItem, optional) — An array that contains your search results. For each match found, the model returns the following fields:
- `page_info` (SearchPageTokenGetResponsesContentApplicationJsonSchemaPageInfo, optional) — An object that provides information about pagination.
- `search_pool` (search_pool, optional) — An object that contains details about the index you queried.

## Errors

### 400 Bad Request Error

The request has failed.

- `error_code` (integer, optional) — Represents the code associated with the error. See the [Error codes](/v1.3/api-reference/error-codes) page for details.
- `message` (string, optional) — A human-readable string describing the error.

## Types

### SearchItem

An object that contains the search results.

- `start` (double, optional) — The start time of the matching video clip, expressed in seconds.
- `end` (double, optional) — The end time of the matching video clip, expressed in seconds.
- `video_id` (string, optional) — 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, optional) — The relevance ranking assigned by the model. Lower numbers indicate higher relevance, starting with 1 for the most relevant result.
- `thumbnail_url` (string, optional) — 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, optional) — A transcription of the spoken words that are captured in the video.
- `id` (string, optional) — 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` (map from string to UserMetadataValue, optional) — Metadata that helps you categorize your assets. The object contains user-defined keys and values, where keys are strings. Each value is a string, a number, a boolean, or an array of strings. Send an integer wider than 53 bits (-9007199254740991 to 9007199254740991), and any identifier you want preserved verbatim, as a string. **Example**: ```JSON "user_metadata": { "category": "recentlyAdded", "batchNumber": 5, "rating": 9.3, "needsReview": true, "hashtags": ["summer", "vlog"] } ```
- `clips` (list of SearchItemClipsItems, optional) — 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.

### SearchPageTokenGetResponsesContentApplicationJsonSchemaPageInfo

An object that provides information about pagination.

- `limit_per_page` (integer, optional) — 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, optional) — A string representing the date and time, in the RFC 3339 format ("YYYY-MM-DDTHH:mm:ssZ"), that the page expires.
- `total_results` (integer, optional) — 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, optional) — When grouping by video, the platform return this field that shows the total number of video clips matching your query.
- `next_page_token` (string, optional) — The unique identifier of the next page.
- `prev_page_token` (string, optional) — The unique identifier of the previous page.

### search_pool

An object that contains details about the index you queried.

- `total_count` (integer, optional) — The number of videos in the index you queried.
- `total_duration` (double, optional) — The total duration of the videos.
- `index_id` (string, optional) — The unique identifier of the index.

### UserMetadataValue

A single metadata value: a string, a number, a boolean, or an array of strings. The platform stores the value with the type you send. It rejects a nested object and an array that contains anything but strings. Send an integer wider than 53 bits (-9007199254740991 to 9007199254740991) and any identifier you want preserved verbatim as a string.

### SearchItemClipsItems

- `start` (double, optional) — The start time of the matching video clip, expressed in seconds.
- `end` (double, optional) — The end time of the matching video clip, expressed in seconds.
- `rank` (integer, optional) — The relevance ranking assigned by the model. Lower numbers indicate higher relevance, starting with 1 for the most relevant result.
- `thumbnail_url` (string, optional) — 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, optional) — A transcription of the spoken words that are captured in the clip.
- `video_id` (string, optional) — A string representing the unique identifier of the video for the corresponding clip.
- `user_metadata` (map from string to UserMetadataValue, optional) — Metadata that helps you categorize your assets. The object contains user-defined keys and values, where keys are strings. Each value is a string, a number, a boolean, or an array of strings. Send an integer wider than 53 bits (-9007199254740991 to 9007199254740991), and any identifier you want preserved verbatim, as a string. **Example**: ```JSON "user_metadata": { "category": "recentlyAdded", "batchNumber": 5, "rating": 9.3, "needsReview": true, "hashtags": ["summer", "vlog"] } ```

## Examples

**Response**

```json
{
  "data": {
    "start": 238.75,
    "end": 259.62109375,
    "video_id": "639963a1ce36463e0199c8c7",
    "rank": 1,
    "thumbnail_url": "https://example.com/thumbnail.jpg"
  },
  "search_pool": {
    "total_count": 10,
    "total_duration": 8731,
    "index_id": "639961c9e219c90227c371a2"
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.twelvelabs.io/v1.3/search/1234567890"

headers = {"x-api-key": "<apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.twelvelabs.io/v1.3/search/1234567890';
const options = {method: 'GET', headers: {'x-api-key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.twelvelabs.io/v1.3/search/1234567890"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("x-api-key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.twelvelabs.io/v1.3/search/1234567890")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["x-api-key"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.twelvelabs.io/v1.3/search/1234567890")
  .header("x-api-key", "<apiKey>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.twelvelabs.io/v1.3/search/1234567890', [
  'headers' => [
    'x-api-key' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.twelvelabs.io/v1.3/search/1234567890");
var request = new RestRequest(Method.GET);
request.AddHeader("x-api-key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["x-api-key": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.twelvelabs.io/v1.3/search/1234567890")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```