Tasks - Avala Documentation

List and retrieve annotation tasks visible to the authenticated user.

List Tasks

GET /api/v1/tasks/

Returns all tasks visible to the authenticated user, with optional filtering by project and status.

Parameters

Name	Type	Required	Description
`project`	string (UUID)	No	Filter by project UID (query parameter)
`status`	string	No	Filter by task status: `pending` or `completed` (query parameter)
`cursor`	string	No	Cursor for pagination (query parameter)
`limit`	integer	No	Number of results per page (query parameter)

Request

curl "https://api.avala.ai/api/v1/tasks/?project=770a9600-a40d-63f6-c938-668877660000&status=pending" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

from avala import Client

client = Client()
tasks = client.tasks.list(project="770a9600-a40d-63f6-c938-668877660000", status="pending")
for task in tasks:
    print(task.uid, task.status)

import Avala from "@avala-ai/sdk";

const avala = new Avala();
const tasks = await avala.tasks.list({
  project: "770a9600-a40d-63f6-c938-668877660000",
  status: "pending",
});
for (const task of tasks.items) {
  console.log(task.uid, task.status);
}

Response

{
  "next": "https://api.avala.ai/api/v1/tasks/?cursor=cD0yMDI1&project=770a9600-a40d-63f6-c938-668877660000",
  "previous": null,
  "results": [
    {
      "uid": "990c1800-b62f-85a8-e150-880099880000",
      "type": "image-annotation",
      "name": "box",
      "status": "pending",
      "project": "770a9600-a40d-63f6-c938-668877660000",
      "created_at": "2025-01-10T08:00:00Z",
      "updated_at": "2025-01-18T14:30:00Z"
    }
  ]
}

Fields

Field	Type	Description
`uid`	string (UUID)	Unique identifier for the task
`type`	string	Task type: `image-annotation`, `video-annotation`, `point-cloud-annotation`, or `point-cloud-objects`
`name`	string	Task name (e.g. `box`, `polygon`, `classification`, `cuboid`)
`status`	string	Current task status (see Task Status Values below)
`project`	string (UUID)	UID of the project this task belongs to
`created_at`	string (datetime)	ISO 8601 timestamp of when the task was created
`updated_at`	string (datetime)	ISO 8601 timestamp of the last update

Get Task

GET /api/v1/tasks/{task_uid}/

Returns a specific task by its unique identifier.

Parameters

Name	Type	Required	Description
`task_uid`	string (UUID)	Yes	Unique identifier of the task (path parameter)

Request

curl "https://api.avala.ai/api/v1/tasks/990c1800-b62f-85a8-e150-880099880000/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

from avala import Client

client = Client()
task = client.tasks.get("990c1800-b62f-85a8-e150-880099880000")
print(task.name, task.status)

import Avala from "@avala-ai/sdk";

const avala = new Avala();
const task = await avala.tasks.get("990c1800-b62f-85a8-e150-880099880000");
console.log(task.name, task.status);

Response

{
  "uid": "990c1800-b62f-85a8-e150-880099880000",
  "type": "image-annotation",
  "name": "box",
  "status": "pending",
  "project": "770a9600-a40d-63f6-c938-668877660000",
  "created_at": "2025-01-10T08:00:00Z",
  "updated_at": "2025-01-18T14:30:00Z"
}

Task Status Values

Status	Description
`pending`	Task has been created and is waiting to be worked on
`completed`	Task has been completed

Task Types

Type	Description
`image-annotation`	2D image annotation tasks
`video-annotation`	Video annotation tasks
`point-cloud-annotation`	3D point cloud annotation tasks
`point-cloud-objects`	Point cloud object detection tasks

Error Responses

Not Found (404)

{
  "detail": "Not found."
}

Returned when the specified task does not exist or is not accessible to the authenticated user.

Permission Denied (403)

{
  "detail": "You do not have permission to perform this action."
}

Returned when the authenticated user does not have access to the requested task.

Unauthorized (401)

{
  "detail": "Invalid API key."
}

Returned when the X-Avala-Api-Key header is missing or contains an invalid key.

​List Tasks

​Parameters

​Request

​Response

​Fields

​Get Task

​Parameters

​Request

​Response

​Task Status Values

​Task Types

​Error Responses

​Not Found (404)

​Permission Denied (403)

​Unauthorized (401)

List Tasks

Parameters

Request

Response

Fields

Get Task

Parameters

Request

Response

Task Status Values

Task Types

Error Responses

Not Found (404)

Permission Denied (403)

Unauthorized (401)