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

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.

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.

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.

Sort by creation date

To sort items by their creation date, invoke the list method on the task object, specifying "created_at" for the sort_by parameter.

from twelvelabs import TwelveLabs

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

tasks = client.task.list(sort_by="created_at")
for task in tasks:
    print(f"id={task.id} status={task.status} created_at={task.created_at}")

import { TwelveLabs } from 'twelvelabs-js';

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

const tasks = await client.task.list({ indexId: indexId, sortBy: 'created_at' });
tasks.forEach((task) => {
  console.log(`id=${task.id} status=${task.status} created_at=${task.createdAt}`);
});

The following output was truncated for brevity:

id=65e86608bb29f13bdd6f3c2e status=pending created_at=2024-03-06T12:48:08.685Z
id=65e865b7bb29f13bdd6f3c2b status=pending created_at=2024-03-06T12:46:47.75Z
id=65e86582bb29f13bdd6f3c28 status=pending created_at=2024-03-06T12:45:54.256Z

Specify the sort order

The example code below demonstrates how to sort items by their creation date in ascending order. Specify "created_at" for the sort_by parameter and "asc" for the sort_option parameter to reverse the default sorting order:

from twelvelabs import TwelveLabs

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

tasks = client.task.list(
    sort_by="created_at",
    sort_option="asc"
    )
for task in tasks:
    print(f"id={task.id} status={task.status} created_at={task.created_at}")

import { TwelveLabs } from 'twelvelabs-js';

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

const tasks = await client.task.list({
  indexId: indexId,
  sortBy: 'created_at',
  sortOption: 'asc',
});
tasks.forEach((task) => {
  console.log(`id=${task.id} status=${task.status} created_at=${task.createdAt}`);
});

The following output was truncated for brevity:

id=65b9f6b79e82682070384431 status=ready created_at=2024-01-31T07:28:55.406Z
id=65b9f6b89e82682070384432 status=ready created_at=2024-01-31T07:28:56.474Z
id=65b9f6b89e82682070384433 status=ready created_at=2024-01-31T07:28:56.522Z

Combine sorting and pagination

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

from twelvelabs import TwelveLabs

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

tasks = client.task.list_pagination(
  sort_by="created_at",
  page_limit=5
)

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

print_page(tasks.data)

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

import { TwelveLab, Task } from 'twelvelabs-js';

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

const tasks = await client.task.listPagination({ sortBy: 'created_at', pageLimit: 5 });
tasks.data.forEach((task: Task) => {
  console.log(`id=${task.id} status=${task.status}`);
});
while (true) {
  const nextPageData = await tasks.next();
  if (!nextPageData) {
    break;
  }
  nextPageData.forEach((task: Task) => {
    console.log(`id=${task.id} status=${task.status} created_at=${task.createdAt}`);
  });
}

The following output was truncated for brevity:

id=65e86608bb29f13bdd6f3c2e status=pending created_at=2024-03-06T12:48:08.685Z
id=65e865b7bb29f13bdd6f3c2b status=pending created_at=2024-03-06T12:46:47.75Z
id=65e86582bb29f13bdd6f3c28 status=pending created_at=2024-03-06T12:45:54.256Z

Use an HTTP client

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

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.

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
  }
}