This page shows how pagination works when performing search requests.

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 expires.
- 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);

// 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 example output below was truncated for brevity:

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'}]

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);

// 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)}`,
    );
  });
}

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);

// 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)}`,
    );
  });
}

Iterative pagination

To retrieve the first page of results, invoke the query method of the search object. To retrieve subsequent pages of results, use the iterator protocol in Python or the async iterator protocol 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 example output below was truncated for brevity:

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"}]

Iterate over the results

The following example code iterates over results by invoking the next function in Python or the next method of the object containing the search results in JavaScript:

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)}`,
    );
  });
}

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)}`,
    );
  });
}

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}`,
      );
    });
  });
}