When listing your indexes, videos, or video indexing tasks, the platform supports the following parameters that allow you to control pagination behavior:

page: A number that identifies the page you want to retrieve. The default value is 1.
page_limit: Specifies the maximum number of items on each page. The default value is 10 and the maximum value is 50.

The examples on this page are specific to listing your indexes. However, the principles demonstrated are similar when listing your video indexing tasks or videos.

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.

Use an SDK

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

The SDKs provide two distinct methods for listing items, 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 for retrieving a specific page, mainly when the total number of items is manageable, or you must fetch a single page of results.
Iterative pagination: Choose this method for iterative navigation through lists, mainly when your application must retrieve a large number of items.

Direct pagination

Retrieve the first page of results

The following example code retrieves the first page of results using the default value for the page and page_limit parameters by invoking the list method of the index object with no parameters:

from twelvelabs import TwelveLabs

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

indexes = client.index.list()
for index in indexes:
    print(
        f"id={index.id} name={index.name} engines={index.engines} created_at={index.created_at}"
    )

import { TwelveLabs } from 'twelvelabs-js';

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

const indexes = await client.index.list();
indexes.forEach((index) => {
  console.log(
    `id=${index.id} name=${index.name} engines=${JSON.stringify(index.engines)} created_at=${index.createdAt}`,
  );
});

The following output was truncated for brevity:

id=65e5ac69bb29f13bdd6f37c4 name=2024-03-04T11:11:36.583Z engines=[Engine(name='pegasus1', options=['visual', 'conversation'], addons=None)] created_at=2024-03-04T11:11:37.393Z
id=65e59606bb29f13bdd6f3794 name=2024-03-04T09:36:06.079Z engines=[Engine(name='pegasus1', options=['visual', 'conversation'], addons=None)] created_at=2024-03-04T09:36:06.791Z
id=65e5945abb29f13bdd6f378c name=2024-03-04T09:28:57.739Z engines=[Engine(name='pegasus1', options=['visual', 'conversation'], addons=None)] created_at=2024-03-04T09:28:58.473Z

Retrieve a specific page

The following example code uses the page parameter to retrieve a specific page (2):

from twelvelabs import TwelveLabs

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

indexes = client.index.list(page=2)
for index in indexes:
    print(
        f"id={index.id} name={index.name} engines={index.engines} created_at={index.created_at}"
    )

import { TwelveLabs } from 'twelvelabs-js';

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

const indexes = await client.index.list({ page: 2 });
indexes.forEach((index) => {
  console.log(
    `id=${index.id} name=${index.name} engines=${JSON.stringify(index.engines)} created_at=${index.createdAt}`,
  );
});

The following output was truncated for brevity:

id=65e567dabb29f13bdd6f372f name=2024-03-04T06:19:05.798Z engines=[Engine(name='pegasus1', options=['visual', 'conversation'], addons=None)] created_at=2024-03-04T06:19:06.468Z
id=65e56706bb29f13bdd6f372e name=2024-03-04T06:15:33.863Z engines=[Engine(name='pegasus1', options=['visual', 'conversation'], addons=None)] created_at=2024-03-04T06:15:34.522Z
id=65e566f9bb29f13bdd6f372d name=2024-03-04T06:15:20.859Z engines=[Engine(name='pegasus1', options=['visual', 'conversation'], addons=None)] created_at=2024-03-04T06:15:21.52Z

If the number of items on a page is less than the maximum number of items the platform should return on that page, you've reached the end of the dataset.

Limits

The following example code uses the page_limit parameter to specify a limit of 2 items on each page:

from twelvelabs import TwelveLabs

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

indexes = client.index.list(page_limit=2)
for index in indexes:
    print(
        f"id={index.id} name={index.name} engines={index.engines} created_at={index.created_at}"
    )

import { TwelveLabs } from 'twelvelabs-js';

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

const indexes = await client.index.list({ pageLimit: 2 });
indexes.forEach((index) => {
  console.log(
    `id=${index.id} name=${index.name} engines=${JSON.stringify(index.engines)} created_at=${index.createdAt}`,
  );
});

The output should look similar to the following one:

id=65e71802bb29f13bdd6f38d8 name=2024-03-05T13:02:57.938Z engines=[Engine(name='pegasus1', options=['visual', 'conversation'], addons=None), Engine(name='marengo2.5', options=['visual', 'conversation', 'text_in_video'], addons=None)] created_at=2024-03-05T13:02:58.531Z
id=65e5ac69bb29f13bdd6f37c4 name=2024-03-04T11:11:36.583Z engines=[Engine(name='pegasus1', options=['visual', 'conversation'], addons=None)] created_at=2024-03-04T11:11:37.393Z

Iterative pagination

To retrieve the first page of results, invoke the list_pagination method of the index object. To retrieve subsequent pages of results, invoke the next method of the indexes 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 using the default value for the page and page_limit parameters by invoking the list_pagination method of the index object with no parameters:

from twelvelabs import TwelveLabs

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

indexes = client.index.list_pagination()

# Utility function to print a specific page
def print_page(page):
  for index in page:
    print(
        f"id={index.id} name={index.name} engines={index.engines} created_at={index.created_at}"
    )

print_page(indexes.data)

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

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

const indexes = await client.index.listPagination();
indexes.data.forEach((index: Index) => {
  console.log(
    `id=${index.id} name=${index.name} engines=${JSON.stringify(index.engines)} created_at=${index.createdAt}`,
  );

The following example output was truncated for brevity:

id=65e71802bb29f13bdd6f38d8 name=2024-03-05T13:02:57.938Z engines=[Engine(name='pegasus1', options=['visual', 'conversation'], addons=None), Engine(name='marengo2.5', options=['visual', 'conversation', 'text_in_video'], addons=None)] created_at=2024-03-05T13:02:58.531Z
id=65e5ac69bb29f13bdd6f37c4 name=2024-03-04T11:11:36.583Z engines=[Engine(name='pegasus1', options=['visual', 'conversation'], addons=None)] created_at=2024-03-04T11:11:37.393Z
id=65e59606bb29f13bdd6f3794 name=2024-03-04T09:36:06.079Z engines=[Engine(name='pegasus1', options=['visual', 'conversation'], addons=None)] created_at=2024-03-04T09:36:06.791Z

Iterate over the results

The following example code iterates over results using the default value for the page and page_limit parameters by invoking the list_pagination method of the index object with no parameters:

from twelvelabs import TwelveLabs

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

indexes = client.index.list_pagination()

# Utility function to print a specific page
def print_page(page):
  for index in page:
    print(
        f"id={index.id} name={index.name} engines={index.engines} created_at={index.created_at}"
    )

print_page(indexes.data)

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

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

  const client = new TwelveLabs({ apiKey: '<YOUR_API_KEY>'});
  
  const indexes = await client.index.listPagination();
  indexes.data.forEach((index: Index) => {
    console.log(
      `id=${index.id} name=${index.name} engines=${JSON.stringify(index.engines)} created_at=${index.createdAt}`,
    );
  });
  while (true) {
    const nextPageData = await indexes.next();
    if (!nextPageData) {
      break;
    }
    nextPageData.forEach((index: Index) => {
      console.log(
        `id=${index.id} name=${index.name} engines=${JSON.stringify(index.engines)} created_at=${index.createdAt}`,
      );
    });
  }

The following example output was truncated for brevity:

id=65e71802bb29f13bdd6f38d8 name=2024-03-05T13:02:57.938Z engines=[Engine(name='pegasus1', options=['visual', 'conversation'], addons=None), Engine(name='marengo2.5', options=['visual', 'conversation', 'text_in_video'], addons=None)] created_at=2024-03-05T13:02:58.531Z
id=65e5ac69bb29f13bdd6f37c4 name=2024-03-04T11:11:36.583Z engines=[Engine(name='pegasus1', options=['visual', 'conversation'], addons=None)] created_at=2024-03-04T11:11:37.393Z
id=65e59606bb29f13bdd6f3794 name=2024-03-04T09:36:06.079Z engines=[Engine(name='pegasus1', options=['visual', 'conversation'], addons=None)] created_at=2024-03-04T09:36:06.791Z
id=65e5945abb29f13bdd6f378c name=2024-03-04T09:28:57.739Z engines=[Engine(name='pegasus1', options=['visual', 'conversation'], addons=None)] created_at=2024-03-04T09:28:58.473Z

Specify limits

The following example code iterates over results and specifies a limit of 5 items on each page:

from twelvelabs import TwelveLabs

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

indexes = client.index.list_pagination(page_limit=5)

# Utility function to print a specific page
def print_page(page):
  for index in page:
    print(
        f"id={index.id} name={index.name} engines={index.engines} created_at={index.created_at}"
    )

print_page(indexes.data)

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

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

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

const indexes = await client.index.listPagination({pageLimit:5});
indexes.data.forEach((index: Index) => {
  console.log(
    `id=${index.id} name=${index.name} engines=${JSON.stringify(index.engines)} created_at=${index.createdAt}`,
  );
});
while (true) {
  const nextPageData = await indexes.next();
  if (!nextPageData) {
    break;
  }
  nextPageData.forEach((index: Index) => {
    console.log(
      `id=${index.id} name=${index.name} engines=${JSON.stringify(index.engines)} created_at=${index.createdAt}`,
    );
  });
}

The following example output was truncated for brevity:

id=65e71802bb29f13bdd6f38d8 name=2024-03-05T13:02:57.938Z engines=[Engine(name='pegasus1', options=['visual', 'conversation'], addons=None), Engine(name='marengo2.5', options=['visual', 'conversation', 'text_in_video'], addons=None)] created_at=2024-03-05T13:02:58.531Z
id=65e5ac69bb29f13bdd6f37c4 name=2024-03-04T11:11:36.583Z engines=[Engine(name='pegasus1', options=['visual', 'conversation'], addons=None)] created_at=2024-03-04T11:11:37.393Z
id=65e59606bb29f13bdd6f3794 name=2024-03-04T09:36:06.079Z engines=[Engine(name='pegasus1', options=['visual', 'conversation'], addons=None)] created_at=2024-03-04T09:36:06.791Z
id=65e5945abb29f13bdd6f378c name=2024-03-04T09:28:57.739Z engines=[Engine(name='pegasus1', options=['visual', 'conversation'], addons=None)] created_at=2024-03-04T09:28:58.473Z

Use an HTTP client

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

To separate the endpoint and the query parameters, you must use a ? symbol. If you add multiple query parameters, you must separate them using the & symbol as shown in this example: page=2&page_limit=5.

To paginate through results, begin with a page value of 1 and a page_limit value of X. To retrieve the next page, set the page parameter to 2, while the page_limit parameter remains the same. To retrieve the rest of the pages, you must subsequently increment the value of the page parameter by 1.

Each response contains, among other information, the items on the page you requested, the page you retrieved, and the total number of pages. When the page you've retrieved is equal to the total number of pages, you've reached the end of the dataset.

📘
Note

For a description of each field in the response, see the API Reference > Indexes section.

Retrieve the first page of results

The following example code retrieves the first page of results using the default value for the page and page_limit parameters by calling the GET method of the /tasks endpoint with no parameters:

TASKS_URL = f"{API_URL}/tasks"
response = requests.get(TASKS_URL, headers=headers)
print (f"Status code: {response.status_code}")
pprint(response.json())

const TASKS_URL = `${API_URL}/tasks`
const config = {
  method: 'get',
  url: TASKS_URL,
  headers: headers,
}
const resp = await axios(config)
const response = await resp.data
console.log(`Status code: ${resp.status}`)
console.log(response)

The following example output was truncated for brevity:

Status code: 200
{
  "data": [
    {
      "_id": "6283ab5ef18e21febd160bc3",
      "created_at": "2022-05-17T14:04:14.001Z",
      "estimated_time": "2022-05-17T14:15:14.667Z",
      "index_id": "6283aa51f18e21febd160bc0",
      "metadata": {
        "duration": 966.598967,
        "filename": "01.mp4",
        "height": 480,
        "width": 854
      },
      "status": "ready",
      "updated_at": "2022-05-17T14:16:44.857Z"
    },
    {
      "_id": "627de9b1f18e21febd160baa",
      "created_at": "2022-05-13T05:16:33.803Z",
      "estimated_time": "2022-05-13T05:29:18.548Z",
      "index_id": "627de802f18e21febd160ba9",
      "metadata": {
        "duration": 30.033333,
        "filename": "10.mp4",
        "height": 270,
        "width": 480
      },
      "status": "ready",
      "updated_at": "2022-05-13T05:31:05.562Z"
    }
  ],
  "page_info": {
    "limit_per_page": 10,
    "page": 1,
    "total_page": 5,
    "total_results": 43
  }
}

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

The limit_per_page property shows that the number of items per page is10.
The page property shows that you've retrieved the first page.
The total_page property shows that the total number of pages is5.
The total_results property shows that the total number of results is 43.

Retrieve a specific page

The following example code uses the page query parameter to retrieve a specific page (2):

TASKS_URL = f"{API_URL}/tasks?page=2"
response = requests.get(TASKS_URL, headers=headers)
print (f"Status code: {response.status_code}")
pprint(response.json())

const TASKS_URL = `${API_URL}/indexes/tasks?page=2`
const config = {
  method: 'get',
  url: TASKS_URL,
  headers: headers,
}
const resp = await axios(config)
const response = await resp.data
console.log(`Status code: ${resp.status}`)
console.log(response)

The following example output was truncated for brevity:

Status code: 200
{
  "data": [
    {
      "_id": "6272b337f18e21febd160b7c",
      "created_at": "2022-05-04T17:09:11.799Z",
      "estimated_time": "2022-05-04T17:19:59.401Z",
      "index_id": "6272b335f18e21febd160b7b",
      "metadata": {
        "duration": 30.033333,
        "filename": "11.mp4",
        "height": 270,
        "width": 480
      },
      "status": "ready",
      "updated_at": "2022-05-04T17:21:31.28Z"
    },
    {
      "_id": "626cc87f22c7851fcbe5c88f",
      "created_at": "2022-04-30T05:26:23.629Z",
      "estimated_time": "2022-04-30T05:32:38.085Z",
      "index_id": "626a273122c7851fcbe5c842",
      "metadata": {
        "duration": 30.033333,
        "filename": "20.mp4",
        "height": 270,
        "width": 480
      },
      "status": "ready",
      "updated_at": "2022-04-30T05:33:55.348Z"
    }
  ],
  "page_info": {
    "limit_per_page": 10,
    "page": 2,
    "total_page": 5,
    "total_results": 43
  }
}

In this example output, note that the pageproperty of the page_info object shows that you've retrieved the second page.

Specify limits

The following example code uses the page_limit query parameter to specify a limit of 5 items on each page:

TASKS_URL = f"{API_URL}/tasks/?page=2&page_limit=5"
response = requests.get(TASKS_URL, headers=headers)
print (f"Status code: {response.status_code}")
pprint(response.json())

const TASKS_URL = `${API_URL}/tasks/?page=2&page_limit=5`
const config = {
  method: 'get',
  url: TASKS_URL,
  headers: headers,
}
const resp = await axios(config)
const response = await resp.data
console.log(`Status code: ${resp.status}`)
console.log(response)

The following example output was truncated for brevity:

Status code: 200
{
  "data": [
    {
      "_id": "6283a059f18e21febd160bbd",
      "created_at": "2022-05-17T13:17:13.524Z",
      "estimated_time": "2022-05-17T13:28:55.569Z",
      "index_id": "6283990ff18e21febd160bbb",
      "metadata": {
        "duration": 700.24,
        "filename": "06.mp4",
        "height": 480,
        "width": 854
      },
      "status": "ready",
      "updated_at": "2022-05-17T13:30:41.95Z"
    },
    {
      "_id": "627de9b1f18e21febd160baa",
      "created_at": "2022-05-13T05:16:33.803Z",
      "estimated_time": "2022-05-13T05:29:18.548Z",
      "index_id": "627de802f18e21febd160ba9",
      "metadata": {
        "duration": 30.033333,
        "filename": "10.mp4",
        "height": 270,
        "width": 480
      },
      "status": "ready",
      "updated_at": "2022-05-13T05:31:05.562Z"
    }
  ],
  "page_info": {
    "limit_per_page": 5,
    "page": 2,
    "total_page": 9,
    "total_results": 43
  }
}

In this example output, note that the page property of the page_info object shows that the API returned 5 items per page.

Indexes, videos, and tasks

Prerequisites

Use an SDK

Direct pagination

Retrieve the first page of results

Retrieve a specific page

Limits

Iterative pagination

Retrieve the first page of results

Iterate over the results

Specify limits

Use an HTTP client

📘
Note

Retrieve the first page of results

Retrieve a specific page

Specify limits

Prerequisites

Use an SDK

Direct pagination

Retrieve the first page of results

Retrieve a specific page

Limits

Iterative pagination

Retrieve the first page of results

Iterate over the results

Specify limits

Use an HTTP client

📘Note

Retrieve the first page of results

Retrieve a specific page

Specify limits

📘
Note