This page shows how pagination works when performing search requests.

You can interact with the platform using one of the available SDKs or an HTTP client like requests or axios. This guide demonstrates how to use the SDKs, the recommended approach for most scenarios. If you need to make direct HTTP requests, refer to the corresponding pages in API Reference > Make any-to-video search requests page for details.

Prerequisites

You’re familiar with the concepts that are described on the Platform overview page.
You've already created an index, and the Marengo video understanding engine is enabled for this index.
You’ve already uploaded at least one video, and the platform has finished indexing it.

Examples

The SDKs provide two distinct methods, each suited to different use cases and requirements. Selecting the most efficient method is important for optimizing the performance of your application:

Direct pagination: Choose this method mainly when the total number of items is manageable, or you must fetch a single page of results.
Iterative pagination: Choose this method mainly when your application must retrieve a large number of items.

Direct pagination

To retrieve the first page of results, invoke the query method of the search object. The response will contain the following properties:

data: An array containing the first page of results
page_info: An object containing information about pagination:
- limit_per_page: The maximum number of results per page.
- total_results: The total number of results.
- page_expired_at: The time when the current page will expire.
- next_page_token: A token you can use to retrieve the results on the next page. The platform doesn't return this field when you've reached the end of the dataset
- prev_page_token: A token you can use to retrieve the results on the previous page. The platform doesn't return this field when you've retrieved the first page.
pool: An object that contains details about the index you queried.

To retrieve a specific page of results, invoke the by_page_token method of the search object, passing the next_page_token property of the page_info object as the value of the page_token parameter. The response will be similar to the one returned when retrieving the first page of results. When the platform does not return the next_page_token field, you've reached the end of the dataset.

Retrieve the first page of results

To retrieve the first page of results, invoke the query method of the search object:

from twelvelabs import TwelveLabs

client = TwelveLabs(api_key="<YOUR_API_KEY>")

search_results = client.search.query(
  index_id="<YOUR_INDEX_ID>", 
  query_text="<YOUR_QUERY>", 
  options=["YOUR_SEARCH_OPTIONS"]
)

print(f"Page info: {search_results.page_info}")
print(f"Pool: {search_results.pool}")

# Utility function to print a specific page
def print_page(page):
  for clip in page:
    print(
        f"video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence} metadata={clip.metadata}"
    )

print_page(search_results.data)

let searchResults = await client.search.query({
  indexId: '<YOUR_INDEX_ID>',
  queryText: '<YOUR_QUERY>',
  options: ['YOUR_SEARCH_OPTIONS'],
});
console.log(searchResults.pageInfo)
console.log(searchResults.pool)
printPage(searchResults.data);
console.log(searchResults.pageInfo)
// Utility function to print a specific page
function printPage(searchData) {
  (searchData as SearchData[]).forEach((clip) => {
    console.log(
      `video_id=${clip.videoId} score=${clip.score} start=${clip.start} end=${clip.end} confidence=${clip.confidence} metadata=${JSON.stringify(clip.metadata)}`,
    );
  });
}

The output should look similar to the following:

Page info: limit_per_page=10 total_results=93 page_expired_at='2024-03-19T12:43:36Z' next_page_token='74d1190c-2014-4c69-a662-4bfbbbe55bb5-1' prev_page_token=None
Pool: total_count=2 total_duration=1305.0 index_id='65d46e4879384c4778ab30f9'
video_id=65d4700a48db9fa780cb4136 score=84.8 start=164.671875 end=200.71875 confidence=high metadata=[{'type': 'visual'}]
video_id=65d46ef848db9fa780cb4135 score=84.77 start=446.46875 end=470.25 confidence=high metadata=[{'type': 'visual'}]
video_id=65d46ef848db9fa780cb4135 score=84.76 start=167.078125 end=207.1875 confidence=high metadata=[{'type': 'visual'}]
video_id=65d46ef848db9fa780cb4135 score=84.75 start=417.015625 end=436.375 confidence=high metadata=[{'type': 'visual'}]
video_id=65d46ef848db9fa780cb4135 score=84.69 start=118.25 end=134.40625 confidence=high metadata=[{'type': 'visual'}]
video_id=65d46ef848db9fa780cb4135 score=84.67 start=505.859375 end=549.9375 confidence=high metadata=[{'type': 'visual'}]
video_id=65d4700a48db9fa780cb4136 score=84.62 start=585.15625 end=592.6875 confidence=high metadata=[{'type': 'visual'}]
video_id=65d4700a48db9fa780cb4136 score=84.55 start=492.5625 end=522.125 confidence=high metadata=[{'type': 'visual'}]
video_id=65d4700a48db9fa780cb4136 score=84.51 start=215.9375 end=234.28125 confidence=high metadata=[{'type': 'visual'}]
video_id=65d46ef848db9fa780cb4135 score=84.49 start=388.375 end=404.25 confidence=high metadata=[{'type': 'visual'}]

Retrieve a specific page of results

from twelvelabs import TwelveLabs

client = TwelveLabs(api_key="<YOUR_API_KEY>")

search_results = client.search.by_page_token(
  page_token="<YOUR_PAGE_TOKEN>"
)

print(f"Page info: {search_results.page_info}")
print(f"Pool: {search_results.pool}")

# Utility function to print a specific page
def print_page(page):
  for clip in page:
    print(
        f"video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence} metadata={clip.metadata}"
    )

print_page(search_results.data)

import { TwelveLabs, SearchData } from 'twelvelabs-js';

const client = new TwelveLabs({ apiKey: TL_API_KEY});

let searchResults = await client.search.byPageToken('<YOUR_PAGE_TOKEN>')
console.log(searchResults.pageInfo)
console.log(searchResults.pool)
printPage(searchResults.data);
console.log(searchResults.pageInfo)
// Utility function to print a specific page
function printPage(searchData) {
  (searchData as SearchData[]).forEach((clip) => {
    console.log(
      `video_id=${clip.videoId} score=${clip.score} start=${clip.start} end=${clip.end} confidence=${clip.confidence} metadata=${JSON.stringify(clip.metadata)}`,
    );
  });
}

The response should look similar to the following:

Page info: limit_per_page=10 total_results=93 page_expired_at='2024-03-19T13:02:40Z' next_page_token='131f5387-9f96-4c5b-a452-2c4453b12382-2' prev_page_token='131f5387-9f96-4c5b-a452-2c4453b12382-0'
Pool: total_count=2 total_duration=1305.0 index_id='65d46e4879384c4778ab30f9'
video_id=65d4700a48db9fa780cb4136 score=84.46 start=34.46875 end=40.40625 confidence=high metadata=[{'type': 'visual'}]
video_id=65d46ef848db9fa780cb4135 score=84.45 start=276.8125 end=290.4375 confidence=high metadata=[{'type': 'visual'}]
video_id=65d46ef848db9fa780cb4135 score=84.44 start=259.28125 end=273.109375 confidence=high metadata=[{'type': 'visual'}]
video_id=65d4700a48db9fa780cb4136 score=84.43 start=342.6875 end=353.140625 confidence=high metadata=[{'type': 'visual'}]
video_id=65d4700a48db9fa780cb4136 score=84.41 start=110.75 end=122.625 confidence=high metadata=[{'type': 'visual'}]
video_id=65d4700a48db9fa780cb4136 score=84.38 start=612.625 end=631.4375 confidence=high metadata=[{'type': 'visual'}]
video_id=65d4700a48db9fa780cb4136 score=84.37 start=291.75 end=308.265625 confidence=high metadata=[{'type': 'visual'}]
video_id=65d46ef848db9fa780cb4135 score=84.35 start=207.1875 end=225.6875 confidence=high metadata=[{'type': 'visual'}]
video_id=65d46ef848db9fa780cb4135 score=84.33 start=297.96875 end=310.75 confidence=high metadata=[{'type': 'visual'}]
video_id=65d46ef848db9fa780cb4135 score=84.33 start=331.734375 end=338.09375 confidence=high metadata=[{'type': 'visual'}]

Specify limits

The following example code iterates over results and and uses the page_limit parameter to specify a limit of 5 items on each page:

search_results = client.search.query(
  index_id="<YOUR_INDEX_ID", 
  query_text="<YOUR_QUERY>", 
  options=["<YOUR_SEARCH_OPTIONS>"],
  page_limit=5
)

print(f"Page info: {search_results.page_info}")
print(f"Pool: {search_results.pool}")

# Utility function to print a specific page
def print_page(page):
  for clip in page:
    print(
        f"video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence} metadata={clip.metadata}"
    )

print_page(search_results.data)

let searchResults = await client.search.query({
  indexId: '<YOUR_INDEX_ID>',
  queryText: '<YOUR_QUERY>',
  options: ['YOUR_SEARCH_OPTIONS'],
  pageLimit: 5
});
console.log(searchResults.pageInfo)
console.log(searchResults.pool)
printPage(searchResults.data);
console.log(searchResults.pageInfo)
// Utility function to print a specific page
function printPage(searchData) {
  (searchData as SearchData[]).forEach((clip) => {
    console.log(
      `video_id=${clip.videoId} score=${clip.score} start=${clip.start} end=${clip.end} confidence=${clip.confidence} metadata=${JSON.stringify(clip.metadata)}`,
    );
  });
}

The output should look similar to the following:

Page info: limit_per_page=5 total_results=93 page_expired_at='2024-03-19T13:50:56Z' next_page_token='0b9f7078-0ec2-4e2b-924b-d477cfedf4a5-1' prev_page_token=None
Pool: total_count=2 total_duration=1305.0 index_id='65d46e4879384c4778ab30f9'
video_id=65d4700a48db9fa780cb4136 score=84.8 start=164.671875 end=200.71875 confidence=high metadata=[{'type': 'visual'}]
video_id=65d46ef848db9fa780cb4135 score=84.77 start=446.46875 end=470.25 confidence=high metadata=[{'type': 'visual'}]
video_id=65d46ef848db9fa780cb4135 score=84.76 start=167.078125 end=207.1875 confidence=high metadata=[{'type': 'visual'}]
video_id=65d46ef848db9fa780cb4135 score=84.75 start=417.015625 end=436.375 confidence=high metadata=[{'type': 'visual'}]
video_id=65d46ef848db9fa780cb4135 score=84.69 start=118.25 end=134.40625 confidence=high metadata=[{'type': 'visual'}]

Iterative pagination

To retrieve the first page of results, invoke the query method of the search object. To retrieve subsequent pages of results, invoke the next method of the search object. When you've reached the end of the dataset, the next method raises a StopIteration exception in Python or returns null in JavaScript.

Retrieve the first page of results

The following example code retrieves the first page of results by calling the query method of the search object:

from twelvelabs import TwelveLabs

client = TwelveLabs(api_key="<YOUR_API_KEY>")

search_results = client.search.query(
  index_id="<YOUR_INDEX_ID", 
  query_text="<YOUR_QUERY>", 
  options=["visual"]
)

# Utility function to print a specific page
def print_page(page):
  for clip in page:
    print(
        f" video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence} metadata={clip.metadata}"
    )

print_page(search_results.data)

const client = new TwelveLabs({ apiKey: '<YOUR_API_KEY>'});

let searchResults = await client.search.query({
  indexId: '<YOUR_INDEX_ID>',
  queryText: '<YOUR_QUERY>',
  options: ['visual'],
});
printPage(searchResults.data);
// Utility function to print a specific page
function printPage(searchData) {
  (searchData as SearchData[]).forEach((clip) => {
    console.log(
      `video_id=${clip.videoId} score=${clip.score} start=${clip.start} end=${clip.end} confidence=${clip.confidence} metadata=${JSON.stringify(clip.metadata)}`,
    );
  });
}

The output should look similar to the following:

video_id= 65d4700a48db9fa780cb4136 score=84.4 start=377.71875 end=390.46875 confidence=high metadata=[{"type":"visual"}]
video_id= 65d46ef848db9fa780cb4135 score=84.25 start=290.4375 end=297.96875 confidence=high metadata=[{"type":"visual"}]
video_id= 65d4700a48db9fa780cb4136 score=84.24 start=554.90625 end=559.6875 confidence=high metadata=[{"type":"visual"}]
video_id= 65d46ef848db9fa780cb4135 score=83.98 start=171.21875 end=178.0625 confidence=high metadata=[{"type":"visual"}]
video_id= 65d4700a48db9fa780cb4136 score=83.91 start=522.125 end=549.90625 confidence=high metadata=[{"type":"visual"}]
video_id= 65d4700a48db9fa780cb4136 score=83.9 start=0 end=22.84375 confidence=high metadata=[{"type":"visual"}]
video_id= 65d46ef848db9fa780cb4135 score=83.89 start=27.640625 end=40.51875 confidence=high metadata=[{"type":"visual"}]
video_id= 65d4700a48db9fa780cb4136 score=83.88 start=22.84375 end=47.796875 confidence=high metadata=[{"type":"visual"}]
video_id= 65d4700a48db9fa780cb4136 score=83.88 start=671.421875 end=726 confidence=high metadata=[{"type":"visual"}]
video_id= 65d46ef848db9fa780cb4135 score=83.85 start=398.21875 end=404.25 confidence=high metadata=[{"type":"visual"}]

Iterate over the results

The following example code iterates over results by invoking the next method:

from twelvelabs import TwelveLabs

client = TwelveLabs(api_key="<YOUR_API_KEY>")

search_results = client.search.query(
  index_id="<YOUR_INDEX_ID>", 
  query_text="<YOUR_QUERY>", 
  options=["visual"]
)

# Utility function to print a specific page
def print_page(page):
  for clip in page:
    print(
        f"video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence} metadata={clip.metadata}"
    )

print_page(search_results.data)

while True:
    try:
        print_page(next(search_results))
    except StopIteration:
        break

import { TwelveLabs, SearchData } from 'twelvelabs-js';

const client = new TwelveLabs({ apiKey: '<YOUR_API_KEY>'});

let searchResults = await client.search.query({
  indexId: '<YOUR_INDEX_ID>',
  queryText: '<YOUR_QUERY>',
  options: ['visual'],
});
printPage(searchResults.data);
while (true) {
  const page = await searchResults.next();
  if (page === null) break;
  else printPage(page);
}
// Utility function to print a specific page
function printPage(searchData) {
  (searchData as SearchData[]).forEach((clip) => {
    console.log(
      `video_id= ${clip.videoId} score=${clip.score} start=${clip.start} end=${clip.end} confidence=${clip.confidence} metadata=${JSON.stringify(clip.metadata)}`,
    );
  });
}

The following output was truncated for brevity:

video_id=65d6131c48db9fa780cb415f score=85.05 start=377.96875 end=388.671875 confidence=high metadata=[{'type': 'visual'}]
video_id=65d60bcf48db9fa780cb415e score=85.05 start=377.96875 end=388.671875 confidence=high metadata=[{'type': 'visual'}]
video_id=65d60bcf48db9fa780cb415e score=84.93 start=412.75 end=439.84375 confidence=high metadata=[{'type': 'visual'}]

Specify limits

The following example code iterates over results and and uses the page_limit parameter to specify a limit of 5 items on each page:

from twelvelabs import TwelveLabs

client = TwelveLabs(api_key="<YOUR_API_KEY>")

search_results = client.search.query(
  index_id="<YOUR_INDEX_ID>, 
  query_text="<YOUR_QUERY>", 
  options=["visual"],
  page_limit=5
)

# Utility function to print a specific page
def print_page(page):
  for clip in page:
    print(
        f"video_id={clip.video_id} score={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence} metadata={clip.metadata}"
    )
print_page(search_results.data)

while True:
    try:
        print_page(next(search_results))
    except StopIteration:
        break

import { TwelveLabs, SearchData } from 'twelvelabs-js';

const client = new TwelveLabs({ apiKey: '<YOUR_API_KEY>'});

let searchResults = await client.search.query({
  indexId: '<YOUR_INDEX_ID>',
  queryText: '<YOUR_QUERY>',
  options: ['visual'],
  pageLimit: 5,
});
printPage(searchResults.data);
while (true) {
  const page = await searchResults.next();
  if (page === null) break;
  else printPage(page);
}
// Utility function to print a specific page
function printPage(searchData) {
  (searchData as SearchData[]).forEach((clip) => {
    console.log(
      `video_id= ${clip.videoId} thumbnail=${clip.thumbnailUrl} score=${clip.score} start=${clip.start} end=${clip.end} confidence=${clip.confidence} metadata=${JSON.stringify(clip.metadata)}`,
    );
  });
}

The following output was truncated for brevity:

video_id=65d60bcf48db9fa780cb415e score=85.05 start=377.96875 end=388.671875 confidence=high metadata=[{'type': 'visual'}]
video_id=65d6131c48db9fa780cb415f score=85.05 start=377.96875 end=388.671875 confidence=high metadata=[{'type': 'visual'}]
video_id=65d6131c48db9fa780cb415f score=84.93 start=412.75 end=439.84375 confidence=high metadata=[{'type': 'visual'}]

Use pagination in conjunction with grouping

When the response is grouped by video, you can use the page_limit parameter to specify the number of videos the platform will return on each page. The following example code sets the page limit to three and specifies that the result must be grouped by video:

from twelvelabs import TwelveLabs

client = TwelveLabs(api_key="<YOUR_API_KEY>")

search_results = client.search.query(
  index_id="<YOUR_INDEX_ID>", 
  query_text="<YOUR_QUERY>", 
  options=["visual"],
  page_limit=3,
  group_by="video"
)

# Utility function to print a specific page
def print_page(page):
    for video in page:
        print(f"Video id: {video.id}")
        for clip in video.clips:
            print(clip)
            print(
                f"\tscore={clip.score} start={clip.start} end={clip.end} confidence={clip.confidence} metadata={clip.metadata}"
            )

print_page(search_results.data)

while True:
    try:
        print_page(next(search_results))
    except StopIteration:
        break

import { TwelveLabs, GroupByVideoSearchData } from 'twelvelabs-js';

const client = new TwelveLabs({ apiKey: '<YOUR_API_KEY>'});

let searchResults = await client.search.query({
  indexId: '<YOUR_INDEX_ID>'
  queryText: '<YOUR_QUERY>',
  options: ['visual'],
  pageLimit: 3,
  groupBy: 'video',
});
printPage(searchResults);
while (true) {
  const page = await searchResults.next();
  if (page === null) break;
  else printPage(page);
}
// Utility function to print a specific page
function printPage(searchData) {
  (searchData.data as GroupByVideoSearchData[]).forEach((video) => {
    console.log(`videoId=${video.id}`);
    video.clips?.forEach((clip) => {
      console.log(
        `     score=${clip.score} start=${clip.start} end=${clip.end} confidence=${clip.confidence}`,
      );
    });
  });
}

The following output was truncated for brevity:

Video id: 65d60bcf48db9fa780cb415e
score=85.05 start=377.96875 end=388.671875 video_id='65d60bcf48db9fa780cb415e' metadata=[{'type': 'visual'}] confidence='high' thumbnail_url=None module_confidence=None modules=None
	score=85.05 start=377.96875 end=388.671875 confidence=high metadata=[{'type': 'visual'}]
score=84.93 start=412.75 end=439.84375 video_id='65d60bcf48db9fa780cb415e' metadata=[{'type': 'visual'}] confidence='high' thumbnail_url=None module_confidence=None modules=None
	score=84.93 start=412.75 end=439.84375 confidence=high metadata=[{'type': 'visual'}]
score=84.9 start=339.125 end=370.78125 video_id='65d60bcf48db9fa780cb415e' metadata=[{'type': 'visual'}] confidence='high' thumbnail_url=None module_confidence=None modules=None
	score=84.9 start=339.125 end=370.78125 confidence=high metadata=[{'type': 'visual'}]