Indexes and tasks
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}
}
Updated 5 days ago