The GET methods 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.

Prerequisites

You’re familiar with the concepts that are described on the Platform overview 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
  }
}