The GET method of the /indexes, /indexes/videos, and /tasks endpoints support sorting.

You can sort the results of an API query by specifying the sorting criteria and direction as query parameters. To separate the endpoint and the query parameters, you must use a ? symbol. If you add both sorting criteria and direction, you must separate them using the & symbol.

Sorting criteria

Use the sort_by parameter to specify the field you want to sort on. The following options are available:

updated_at: Sorts by the date and time when the item was updated.
created_at: Sorts by the date and time when the item was created.

Sorting direction

Use the sort_option parameter to specify the sorting direction. The following options are available:

asc: For ascending order.
desc: For descending order. This is the default value.

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.

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.

Prerequisites

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

Sort by creation date

The following example code sorts items by creation date, using the sort_by query parameter:

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

const TASKS_URL = `${API_URL}/tasks?sort_by=created_at`
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': 'animal-encounters-07.mp4',
                        'height': 480,
                        'width': 854},
           'status': 'ready',
           'updated_at': '2022-05-17T14:16:44.857Z'},
          {'_id': '6283a0a8f18e21febd160bbf',
           'created_at': '2022-05-17T13:18:32.388Z',
           'estimated_time': '2022-05-17T13:31:26.808Z',
           'index_id': '6283990ff18e21febd160bbb',
           'metadata': {'duration': 966.598967,
                        'filename': 'animal-encounters-04mp4',
                        'height': 480,
                        'width': 854},
           'status': 'ready',
           'updated_at': '2022-05-17T13:31:28.316Z'},
          {'_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': 'car-accidents-02.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 that the default sort order is descending. The most recent items are displayed first at the top of the list.

Specify the sort order

The following example code sorts items by creation date and reverses the sorting order:

TASKS_URL = f"{API_URL}/tasks?sort_by=created_at&sort_option=asc"
response = requests.get(TASKS_URL, headers=headers)
print (f"Status code: {response.status_code}")
print(response.json())

const TASKS_URL = `${API_URL}/tasks?sort_by=created_at&sort_option=asc`
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': '626a229622c7851fcbe5c83b',
           'created_at': '2022-04-28T05:13:58.128Z',
           'estimated_time': '2022-04-28T05:24:25.718Z',
           'index_id': '626a228822c7851fcbe5c83a',
           'metadata': {'duration': 30.033333,
                        'filename': 'animal-encounters-10.mp4',
                        'height': 270,
                        'width': 480},
           'status': 'ready',
           'updated_at': '2022-04-28T05:26:02.849Z'},
          {'_id': '626a24dd22c7851fcbe5c83d',
           'created_at': '2022-04-28T05:23:40.911Z',
           'estimated_time': '2022-04-28T05:24:25.729Z',
           'index_id': '626a24d622c7851fcbe5c83c',
           'metadata': {'duration': 30.033333,
                        'filename': 'test.mp4',
                        'height': 270,
                        'width': 480},
           'status': 'ready',
           'updated_at': '2022-04-28T05:26:02.861Z'},
          {'_id': '626ba02022c7851fcbe5c848',
           'created_at': '2022-04-29T08:21:52.696Z',
           'estimated_time': '2022-04-29T08:30:07.057Z',
           'index_id': '626a273122c7851fcbe5c842',
           'metadata': {'duration': 30.033333,
                        'filename': 'car-accidents-06.mp4',
                        'height': 270,
                        'width': 480},
           'status': 'ready',
           'updated_at': '2022-04-29T08:31:30.053Z'}],
 'page_info': {'limit_per_page': 10,
               'page': 1,
               'total_page': 5,
               'total_results': 43}
}

Combine sorting and pagination

The following example code sorts items by creation date and specifies that each page should contain 5 items:

TASKS_URL = f"{API_URL}/tasks?sort_by=created_at&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?sort_by=created_at&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': '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': 'animal-encounters-03.mp4',
                        'height': 480,
                        'width': 854},
           'status': 'ready',
           'updated_at': '2022-05-17T14:16:44.857Z'},
          {'_id': '6283ab20f18e21febd160bc2',
           'created_at': '2022-05-17T14:03:12.704Z',
           'estimated_time': '2022-05-17T14:14:05.405Z',
           'index_id': '6283aa51f18e21febd160bc0',
           'metadata': {'duration': 700.24,
                        'filename': 'animal-encounters-02.mp4',
                        'height': 480,
                        'width': 854},
           'status': 'ready',
           'updated_at': '2022-05-17T14:16:01.554Z'},
          {'_id': '6283a07ef18e21febd160bbe',
           'created_at': '2022-05-17T13:17:50.564Z',
           'estimated_time': '2022-05-17T13:28:55.578Z',
           'index_id': '6283990ff18e21febd160bbb',
           'metadata': {'duration': 700.24,
                        'filename': 'animal-encounters-02.mp4',
                        'height': 480,
                        'width': 854},
           'status': 'ready',
           'updated_at': '2022-05-17T13:30:54.078Z'}],
 'page_info': {'limit_per_page': 5,
               'page': 1,
               'total_page': 9,
               'total_results': 43}
}