Skip to main content
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

NameTypeRequiredDescription
projectstring (UUID)NoFilter by project UID (query parameter)
statusstringNoFilter by task status: pending or completed (query parameter)
cursorstringNoCursor for pagination (query parameter)
limitintegerNoNumber of results per page (query parameter)

​
Request

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

​
Response

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

​
Fields

FieldTypeDescription
uidstring (UUID)Unique identifier for the task
typestringTask type: image-annotation, video-annotation, point-cloud-annotation, or point-cloud-objects
namestringTask name (e.g. box, polygon, classification, cuboid)
statusstringCurrent task status (see Task Status Values below)
projectstring (UUID)UID of the project this task belongs to
created_atstring (datetime)ISO 8601 timestamp of when the task was created
updated_atstring (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

NameTypeRequiredDescription
task_uidstring (UUID)YesUnique identifier of the task (path parameter)

​
Request

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

​
Response

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

​
Task Status Values

StatusDescription
pendingTask has been created and is waiting to be worked on
completedTask has been completed

​
Task Types

TypeDescription
image-annotation2D image annotation tasks
video-annotationVideo annotation tasks
point-cloud-annotation3D point cloud annotation tasks
point-cloud-objectsPoint 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.