You can interact with the platform using one of the available SDKs or an HTTP client like requests or axios. Follow the steps in one of the sections below, depending on your use case.

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.

Use an SDK

Refer to this section if you use one of the available SDKs.

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="<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>',
  query: '<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="<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>',
  query: '<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="<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>',
  query: '<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="<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>',
  query: '<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="<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>',
  query: '<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="<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>'
  query: '<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'}]

Use an HTTP client

Refer to this section if you use clients such as requests or axios.

The /search endpoint supports the following parameters that allow you to control pagination behavior:

The identifier of the page: The POST method of the /search endpoint returns the first page of results. To retrieve the subsequent page, you must call the GET method of the /search/{page-token} endpoint, passing it the unique identifier of the page you want to retrieve as a path parameter.
The number of items on each page: Set the page_limit parameter in the request body when calling the POST method of the /search endpoint. The default value is 10 and the maximum value is 50.

When making the initial request, you call the POST method of the /search endpoint, passing it a page_limit value of X. The response will contain, among other information, the first page of results, the identifier of the next page, and the time when the page expires. To retrieve the rest of the pages, invoke the GET method of the /search/{page-token} endpoint, replacing the {page-token} path parameter with the identifier of the page that you want to retrieve. When the API does not return the identifier of the next page, you've reached the end of the dataset.

📘
Notes

The GET method of the /search endpoint returns, among other information, a field named page_info.prev_page_token representing the unique identifier of the previous page. When the API does not return the page_info.prev_page_token field, then this is the first page.

The identifiers of the next and previous pages can become invalid when the page expires or items are added or removed. Do not store them in your application. Using an expired or invalid page identifier returns an HTTP 400 token expired or invalid token error.

The platform returns your search results in the form of an array named data, and the page_limit parameter controls the number of elements on each page. When your search results are not grouped, the page_limit parameter specifies the number of matching video clips on each page. On the other hand, when your search results are grouped by video, the page_limit parameter specifies the number of videos on each page.

For a description of each field in the response, see the API Reference > Make a search Request page.

Retrieve the first page of results

The following example code retrieves the first page of results by calling the POST method of the /search endpoint:

SEARCH_URL = f"{API_URL}/search"

data = {
  "query": "bear chasing a man",
  "index_id": INDEX_ID,
  "search_options": ["visual"]
}

response = requests.post(SEARCH_URL, headers=headers, json=data)
print (f'Status code: {response.status_code}')
pprint(response.json())

const SEARCH_URL = `${API_URL}/search`

const data = {
  'query': 'bear chasing a man',
  'index_id': INDEX_ID,
  'search_options': ['visual']
}

const resp = await axios.post(
  SEARCH_URL,
  data,
  {
    'headers': {
      'x-api-key': API_KEY
    }
  }
)
const { data: response } = resp;
console.log(`Status code: ${resp.status}`)
console.log(JSON.stringify(response,null,4))

The following example output was truncated for brevity:

{
  "search_pool": {
    "total_count": 13,
    "total_duration": 8731,
    "index_id": "639961c9e219c90227c371a2"
  },
  "data": [
    {
      "score": 86.17,
      "start": 173,
      "end": 190,
      "video_id": "63996260ce36463e0199c8c5",
      "confidence": "high",
      "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/63996260ce36463e0199c8c5/174.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20221227%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221227T173944Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=23a084fae38430dbb0f7fb05bad5318eafe01eb71328e237cb7ae25ae70924a3"
    },
    {
      "score": 85.4,
      "start": 483,
      "end": 498,
      "video_id": "63996232ce36463e0199c8c3",
      "confidence": "high",
      "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/63996232ce36463e0199c8c3/484.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20221227%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221227T173944Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=600e92cdf3ef3f6ccfed67716e8d04bc7a178bc6bdc72ccd13111ee6343e3ccb"
    },
    {
      "score": 84.99,
      "start": 458,
      "end": 478,
      "video_id": "63996260ce36463e0199c8c5",
      "confidence": "high",
      "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/63996260ce36463e0199c8c5/459.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20221227%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221227T173944Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=71b60dbfe0f149c9dd6880c7a1d8a70cdb553364e83ed171c46962f100fc9202"
    }
  ],
  "page_info": {
    "limit_per_page": 10,
    "total_results": 157,
    "page_expired_at": "2022-12-27T17:39:44Z",
    "next_page_token": "9f161112-1e65-43d7-b10f-0914206c307e-1"
  }
}

In this example output, note the following about the page_info object :

The page_info.next_page_token property shows the identifier of the next page - 9f161112-1e65-43d7-b10f-0914206c307e-1.
The page_info.page_expired_at property shows the time when this page expires - 2022-12-27T17:39:44Z.
The page_info.limit_per_page property shows the number of results on this page - 10.
The page_info.total_result property shows the total number of results - 157.

Retrieve a specific page

The following example code retrieves a specific page by calling the GET method of the /search endpoint, replacing the placeholder surrounded by <> with the identifier of the page you want to retrieve:

SEARCH_URL = f"{API_URL}/search/<YOUR_PAGE_TOKEN>"

response = requests.get(SEARCH_URL, headers=headers)
print (f'Status code: {response.status_code}')
pprint(response.json())

const SEARCH_URL = `${API_URL}/search/<YOUR_PAGE_TOKEN>`

const resp = await axios.get(
  SEARCH_URL,
  {
    'headers': {
      'x-api-key': API_KEY
    }
  }
)
const { data: response } = resp;
console.log(`Status code: ${resp.status}`)
console.log(JSON.stringify(response,null,4))

The following example output was truncated for brevity:

{
  "search_pool": {
    "total_count": 13,
    "total_duration": 8731,
    "index_id": "639961c9e219c90227c371a2"
  },
  "data": [
    {
      "score": 84.98,
      "start": 419,
      "end": 433,
      "video_id": "63996232ce36463e0199c8c3",
      "confidence": "high",
      "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/63996232ce36463e0199c8c3/420.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20221228%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221228T061937Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=aa684e88065c75c024c202793c98dc2e3501692b6f14fcea9e9e105ec583f83e"
    },
    {
      "score": 84.52,
      "start": 409,
      "end": 417,
      "video_id": "63a2a2a7ce36463e0199c8e5",
      "confidence": "high",
      "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/63a2a2a7ce36463e0199c8e5/410.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20221228%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221228T061936Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=4e519ad017063ca9ee3ec44a75d01291ae55651a68a1a5ffe77a24a940e22b1f"
    },
    {
      "score": 83.78,
      "start": 788,
      "end": 796,
      "video_id": "63996260ce36463e0199c8c5",
      "confidence": "high",
      "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/63996260ce36463e0199c8c5/789.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20221228%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221228T061937Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=0c1d1bbac8abed8e9d20c3ea188337fe38e779bc5ffa27da7714858393389f87"
    }
  ],
  "page_info": {
    "limit_per_page": 10,
    "total_results": 157,
    "page_expired_at": "2022-12-28T06:19:37Z",
    "next_page_token": "dacfcbf3-7a1b-458e-b4af-bf7b0632faf5-2",
    "prev_page_token": "dacfcbf3-7a1b-458e-b4af-bf7b0632faf5-0"
  }
}

In this example output, note the following about the page_info object :

The page_infonext_page_token property shows the identifier of the next page - dacfcbf3-7a1b-458e-b4af-bf7b0632faf5-2.
The page_info.page_expired_at property shows the time when this page expires - 2022-12-28T06:19:37Z.
The page_info.prev_page_token property shows the identifier of the previous page - dacfcbf3-7a1b-458e-b4af-bf7b0632faf5-0.

Specify limits

The following example code specifies a limit of 3 items on each page using the page_limit parameter:

SEARCH_URL = f"{API_URL}/search"

data = {
  "query": "bear chasing a man",
  "page_limit": 3,
  "index_id": INDEX_ID,
  "search_options": ["visual"]
}

response = requests.post(SEARCH_URL, headers=headers, json=data)
print (f'Status code: {response.status_code}')
pprint(response.json())

const SEARCH_URL = `${API_URL}/search`

const data = {
  'query': 'bear chasing a man',
  'page_limit': 3,
  'index_id': INDEX_ID,
  'search_options': ['visual']
}

const resp = await axios.post(
  SEARCH_URL,
  data,
  {
    'headers': {
      'x-api-key': API_KEY
    }
  }
)
const { data: response } = resp;
console.log(`Status code: ${resp.status}`)
console.log(JSON.stringify(response,null,4))

The output should look similar to the following one:

{
  "search_pool": {
    "total_count": 13,
    "total_duration": 8731,
    "index_id": "639961c9e219c90227c371a2"
  },
  "data": [
    {
      "score": 86.17,
      "start": 173,
      "end": 190,
      "video_id": "63996260ce36463e0199c8c5",
      "confidence": "high",
      "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/63996260ce36463e0199c8c5/174.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20221228%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221228T063135Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=5fefe9d67803ac45ad8a8a5720404ef7e571cae29341028a26904e2039d40a1c"
    },
    {
      "score": 86.14,
      "start": 624,
      "end": 630,
      "video_id": "63996246ce36463e0199c8c4",
      "confidence": "high",
      "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/63996246ce36463e0199c8c4/625.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20221228%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221228T063135Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=a79633803efb8d501c9c19104d6aa1b6ff270566f9438bd05027dc3c13908f8e"
    },
    {
      "score": 86.03,
      "start": 149,
      "end": 173,
      "video_id": "63996260ce36463e0199c8c5",
      "confidence": "high",
      "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/63996260ce36463e0199c8c5/150.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20221228%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221228T063135Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=160dc91ef266c91532e2fe61eb629734645c8a51f89df04d011783ad8edf21b2"
    }
  ],
  "page_info": {
    "limit_per_page": 3,
    "total_results": 157,
    "page_expired_at": "2022-12-28T06:31:35Z",
    "next_page_token": "86d9bd56-9f57-4591-8542-0a6f4926951e-1"
  }
}

In this example output, note that the limit_per_page property of the page_info object shows that the platform returned three items per page.

Using pagination in conjunction with grouping

SEARCH_URL = f"{API_URL}/search"

data = {
  "query": "car accidents",
  "index_id": INDEX_ID,
  "search_options": ["visual"],
  "page_limit": 3,
  "group_by": "video"
}

response = requests.post(SEARCH_URL, headers=headers, json=data)
print(f"Status code: {response.status_code}")
pprint(response.json())

const SEARCH_URL = `${API_URL}/search`

const data = {
  'query': 'car accidents',
  'index_id': INDEX_ID,
  'search_options': ['visual'],
  'page_limit': 3,
  'group_by': 'video'
}

const resp = await axios.post(
  SEARCH_URL,
  data,
  {
    'headers': {
      'x-api-key': API_KEY
    }
  }
)
const { data: response } = resp;
console.log(`Status code: ${resp.status}`)
console.log(JSON.stringify(response,null,4))

The output should look similar to the following one:

{
  "search_pool": {
    "total_count": 15,
    "total_duration": 10228,
    "index_id": "639961c9e219c90227c371a2"
  },
  "data": [
    {
      "clips": [
        {
          "score": 81.79,
          "start": 117.8359375,
          "end": 125.71875,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "639963a1ce36463e0199c8c7",
          "confidence": "medium",
          "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/639963a1ce36463e0199c8c7/118.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20230116%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230116T111230Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=b6dc36209991885951423fd2250f7397f46e5a482cf773c13e66025a12831113"
        },
        {
          "score": 76.8,
          "start": 266.765625,
          "end": 270.5,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "639963a1ce36463e0199c8c7",
          "confidence": "medium",
          "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/639963a1ce36463e0199c8c7/267.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20230116%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230116T111230Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=dbfdfcf8945bf2f2315e2845e5c30f0470e5a3361e734bcb9cf70e461cb00eb5"
        },
        {
          "score": 75.61,
          "start": 422.21875,
          "end": 428.21875,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "639963a1ce36463e0199c8c7",
          "confidence": "medium",
          "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/639963a1ce36463e0199c8c7/423.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20230116%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230116T111230Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=66612d0c9fac75a5bbbf6ba155992c25f8cd1cd3a2613fae0fd569460cb95db0"
        },
        {
          "score": 74.9,
          "start": 485.53125,
          "end": 489.53125,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "639963a1ce36463e0199c8c7",
          "confidence": "medium",
          "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/639963a1ce36463e0199c8c7/486.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20230116%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230116T111230Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=927c2f32cb10a7616464f695a4b61ae7e8533c47783c66bea1603aeec896121a"
        }
      ],
      "id": "639963a1ce36463e0199c8c7"
    },
    {
      "clips": [
        {
          "score": 77.29,
          "start": 27.3984375,
          "end": 31.375,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "63b2c707ce36463e0199c906",
          "confidence": "medium",
          "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/63b2c707ce36463e0199c906/28.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20230116%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230116T111230Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=f83a05ba9ea3e87e6564d450056b183bde8d8c4aa02a95ecd050c7f2ca97c979"
        },
        {
          "score": 75.26,
          "start": 565.8125,
          "end": 569.15625,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "63b2c707ce36463e0199c906",
          "confidence": "medium",
          "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/63b2c707ce36463e0199c906/566.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20230116%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230116T111230Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=cbddd6c0464cccba21593bb2f28b2b835567c47dca4dfc7f3e0b51d4b6862cc4"
        }
      ],
      "id": "63b2c707ce36463e0199c906"
    },
    {
      "clips": [
        {
          "score": 75.73,
          "start": 703.90625,
          "end": 706.375,
          "metadata": [
            {
              "type": "visual"
            }
          ],
          "video_id": "6399637ace36463e0199c8c6",
          "confidence": "medium",
          "thumbnail_url": "https://project-one-thumbnail.s3.us-west-2.amazonaws.com/6399637ace36463e0199c8c6/704.jpeg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYRWJPOVHXE5SJ77T%2F20230116%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20230116T111230Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&x-id=GetObject&X-Amz-Signature=0c6e1eddc437bc7a0cfdd17b7927c5adb6850a4ebd41cfe021956c4d7220aeeb"
        }
      ],
      "id": "6399637ace36463e0199c8c6"
    }
  ],
  "page_info": {
    "limit_per_page": 3,
    "total_results": 5,
    "total_inner_matches": 9,
    "page_expired_at": "2023-01-16T11:12:30Z",
    "next_page_token": "59ae2f31-5c86-48be-8dfb-a76433656df5-1"
  }
}

Note the following about this example output:

The data array is composed of three objects as specified by the page_limit parameter. Each object corresponds to a video that matches your query and is formed of the following key-value pairs:
- clips: An array that groups the information about all the matching video clips in that video.
- id: The unique identifier of the video that matched your query.
The page_info.total_results field shows the number of videos that matched your search query (5).
The page_info.total_inner_matches field shows the number of video clips that matched your query. In this example, a total of nine clips in five videos matched your query.

Search results

Prerequisites

Use an SDK

Direct pagination

Retrieve the first page of results

Retrieve a specific page of results

Specify limits

Iterative pagination

Retrieve the first page of results

Iterate over the results

Specify limits

Use pagination in conjunction with grouping

Use an HTTP client

📘
Notes

Retrieve the first page of results

Retrieve a specific page

Specify limits

Using pagination in conjunction with grouping

Prerequisites

Use an SDK

Direct pagination

Retrieve the first page of results

Retrieve a specific page of results

Specify limits

Iterative pagination

Retrieve the first page of results

Iterate over the results

Specify limits

Use pagination in conjunction with grouping

Use an HTTP client

📘Notes

Retrieve the first page of results

Retrieve a specific page

Specify limits

Using pagination in conjunction with grouping

📘
Notes