Indexes and tasks

The GET methods of the /indexes, /indexes/videos, and /tasks endpoints support the following query 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.

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

Examples

The examples in this section are specific to using the /tasks endpoint. However, the principles demonstrated are similar when using the /indexes and /indexes/videos endpoints.

The examples in this section assume the following:

  • You have a valid Twelve Labs account. For details about creating an account and retrieving your API key, see the Authentication page.
  • Youโ€™re familiar with the concepts that are described on the Quickstart page.

Note that, although the example code in this guide is written in Python and Node.js the API is compatible with most programming languages, and you can also use Postman or other REST clients to send requests and view responses.

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

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.