> ## Documentation Index
> Fetch the complete documentation index at: https://avala.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tasks

> API reference for annotation tasks

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

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.avala.ai/api/v1/tasks/?project=770a9600-a40d-63f6-c938-668877660000&status=pending" \
    -H "X-Avala-Api-Key: $AVALA_API_KEY"
  ```

  ```python Python theme={null}
  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)
  ```

  ```typescript TypeScript theme={null}
  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);
  }
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.avala.ai/api/v1/tasks/990c1800-b62f-85a8-e150-880099880000/" \
    -H "X-Avala-Api-Key: $AVALA_API_KEY"
  ```

  ```python Python theme={null}
  from avala import Client

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

  ```typescript TypeScript theme={null}
  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);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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)

```json theme={null}
{
  "detail": "Not found."
}
```

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

### Permission Denied (403)

```json theme={null}
{
  "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)

```json theme={null}
{
  "detail": "Invalid API key."
}
```

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