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

# Tasks

> Create and manage annotation tasks via the REST API

## Overview

Tasks in CVAT represent individual annotation assignments. Each task contains media files (images or videos) and can be divided into multiple jobs for parallel annotation.

## List Tasks

Retrieve a list of all tasks accessible to you.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://app.cvat.ai/api/tasks" \
    -H "Authorization: Token <your_token>"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://app.cvat.ai/api/tasks",
      headers={"Authorization": "Token <your_token>"}
  )
  tasks = response.json()
  ```
</CodeGroup>

### Query Parameters

<ParamField query="name" type="string">
  Filter by task name
</ParamField>

<ParamField query="owner" type="string">
  Filter by owner username
</ParamField>

<ParamField query="assignee" type="string">
  Filter by assignee username
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `annotation`, `validation`, or `completed`
</ParamField>

<ParamField query="project_id" type="integer">
  Filter by project ID
</ParamField>

<ParamField query="project_name" type="string">
  Filter by project name
</ParamField>

<ParamField query="mode" type="string">
  Filter by annotation mode
</ParamField>

<ParamField query="dimension" type="string">
  Filter by dimension: `2d` or `3d`
</ParamField>

<ParamField query="subset" type="string">
  Filter by dataset subset
</ParamField>

<ParamField query="validation_mode" type="string">
  Filter by validation mode: `gt` or `gt_pool`
</ParamField>

<ParamField query="search" type="string">
  Search tasks by multiple fields
</ParamField>

<ParamField query="sort" type="string">
  Sort by field name (prefix with `-` for descending)
</ParamField>

<ParamField query="page" type="integer">
  Page number for pagination
</ParamField>

<ParamField query="page_size" type="integer">
  Number of results per page
</ParamField>

## Create a Task

Create a new annotation task. Note that the task will be created without media files - use the data endpoint to upload them.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.cvat.ai/api/tasks" \
    -H "Authorization: Token <your_token>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Street Scenes Annotation",
      "project_id": 1,
      "labels": [
        {
          "name": "car",
          "color": "#ff0000"
        }
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://app.cvat.ai/api/tasks",
      headers={"Authorization": "Token <your_token>"},
      json={
          "name": "Street Scenes Annotation",
          "project_id": 1,
          "labels": [
              {"name": "car", "color": "#ff0000"}
          ]
      }
  )
  task = response.json()
  ```
</CodeGroup>

### Request Body

<ParamField body="name" type="string" required>
  Task name
</ParamField>

<ParamField body="project_id" type="integer">
  ID of the parent project
</ParamField>

<ParamField body="labels" type="array">
  Array of label definitions (required if not in a project)
</ParamField>

<ParamField body="owner_id" type="integer">
  User ID of the task owner
</ParamField>

<ParamField body="assignee_id" type="integer">
  User ID of the task assignee
</ParamField>

<ParamField body="bug_tracker" type="string">
  Bug tracker URL
</ParamField>

<ParamField body="subset" type="string">
  Dataset subset (train, val, test)
</ParamField>

<ParamField body="segment_size" type="integer">
  Number of frames per job segment
</ParamField>

<ParamField body="overlap" type="integer">
  Frame overlap between segments
</ParamField>

<ParamField body="source_storage" type="object">
  Source storage configuration
</ParamField>

<ParamField body="target_storage" type="object">
  Target storage configuration
</ParamField>

### Response

<ResponseField name="id" type="integer">
  Task ID
</ResponseField>

<ResponseField name="name" type="string">
  Task name
</ResponseField>

<ResponseField name="project_id" type="integer">
  Parent project ID
</ResponseField>

<ResponseField name="owner" type="object">
  Task owner details
</ResponseField>

<ResponseField name="assignee" type="object">
  Task assignee details
</ResponseField>

<ResponseField name="status" type="string">
  Task status: `annotation`, `validation`, or `completed`
</ResponseField>

<ResponseField name="labels" type="array">
  Array of label definitions
</ResponseField>

<ResponseField name="created_date" type="string">
  Task creation timestamp
</ResponseField>

<ResponseField name="updated_date" type="string">
  Task last update timestamp
</ResponseField>

## Get Task Details

Retrieve details of a specific task.

```bash theme={null}
curl -X GET "https://app.cvat.ai/api/tasks/{id}" \
  -H "Authorization: Token <your_token>"
```

### Path Parameters

<ParamField path="id" type="integer" required>
  Unique task identifier
</ParamField>

## Update a Task

Update task properties, labels, or move between projects.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PATCH "https://app.cvat.ai/api/tasks/{id}" \
    -H "Authorization: Token <your_token>" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Updated Task Name",
      "status": "validation"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.patch(
      f"https://app.cvat.ai/api/tasks/{task_id}",
      headers={"Authorization": "Token <your_token>"},
      json={
          "name": "Updated Task Name",
          "assignee_id": 5
      }
  )
  updated_task = response.json()
  ```
</CodeGroup>

### Path Parameters

<ParamField path="id" type="integer" required>
  Unique task identifier
</ParamField>

### Request Body Examples

#### Update Task Properties

```json theme={null}
{
  "name": "New Task Name",
  "assignee_id": 5,
  "bug_tracker": "https://github.com/org/repo/issues",
  "subset": "train"
}
```

#### Move Task to Project

```json theme={null}
{
  "project_id": 10
}
```

#### Transfer Task to Organization

```json theme={null}
{
  "organization_id": 1
}
```

## Delete a Task

Delete a task along with all its jobs, annotations, and data.

```bash theme={null}
curl -X DELETE "https://app.cvat.ai/api/tasks/{id}" \
  -H "Authorization: Token <your_token>"
```

<Warning>
  Deleting a task permanently removes all associated jobs, annotations, and uploaded media files.
</Warning>

### Path Parameters

<ParamField path="id" type="integer" required>
  Unique task identifier
</ParamField>

## Upload Task Data

Upload media files (images or videos) to a task.

<CodeGroup>
  ```bash cURL - Images theme={null}
  curl -X POST "https://app.cvat.ai/api/tasks/{id}/data" \
    -H "Authorization: Token <your_token>" \
    -F "image_quality=70" \
    -F "client_files[0]=@image1.jpg" \
    -F "client_files[1]=@image2.jpg" \
    -F "client_files[2]=@image3.jpg"
  ```

  ```bash cURL - Video theme={null}
  curl -X POST "https://app.cvat.ai/api/tasks/{id}/data" \
    -H "Authorization: Token <your_token>" \
    -F "image_quality=70" \
    -F "client_files[0]=@video.mp4"
  ```

  ```python Python theme={null}
  import requests

  files = [
      ('client_files[0]', open('image1.jpg', 'rb')),
      ('client_files[1]', open('image2.jpg', 'rb')),
      ('client_files[2]', open('image3.jpg', 'rb'))
  ]

  data = {'image_quality': 70}

  response = requests.post(
      f"https://app.cvat.ai/api/tasks/{task_id}/data",
      headers={"Authorization": "Token <your_token>"},
      files=files,
      data=data
  )
  ```
</CodeGroup>

### Path Parameters

<ParamField path="id" type="integer" required>
  Unique task identifier
</ParamField>

### Form Parameters

<ParamField body="client_files" type="array" required>
  Array of image or video files
</ParamField>

<ParamField body="image_quality" type="integer" default={70}>
  Image compression quality (0-100)
</ParamField>

<ParamField body="use_zip_chunks" type="boolean" default={true}>
  Use zip chunks for image sets
</ParamField>

<ParamField body="cloud_storage_id" type="integer">
  Cloud storage ID for remote data
</ParamField>

<ParamField body="server_files" type="array">
  Server file paths for server-side data
</ParamField>

<ParamField body="remote_files" type="array">
  Remote file URLs
</ParamField>

## Get Task Annotations

Retrieve all annotations for a task.

```bash theme={null}
curl -X GET "https://app.cvat.ai/api/tasks/{id}/annotations/" \
  -H "Authorization: Token <your_token>"
```

### Path Parameters

<ParamField path="id" type="integer" required>
  Unique task identifier
</ParamField>

### Response

<ResponseField name="version" type="integer">
  Annotation format version
</ResponseField>

<ResponseField name="tags" type="array">
  Array of image-level tags
</ResponseField>

<ResponseField name="shapes" type="array">
  Array of shape annotations (rectangles, polygons, etc.)
</ResponseField>

<ResponseField name="tracks" type="array">
  Array of tracked objects across frames
</ResponseField>

## Import Task Annotations

Import annotations from a file.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://app.cvat.ai/api/tasks/{id}/annotations/?format=COCO%201.0" \
    -H "Authorization: Token <your_token>" \
    -F "annotation_file=@annotations.json"
  ```

  ```python Python theme={null}
  import requests

  with open('annotations.json', 'rb') as f:
      files = {'annotation_file': f}
      response = requests.post(
          f"https://app.cvat.ai/api/tasks/{task_id}/annotations/",
          headers={"Authorization": "Token <your_token>"},
          params={"format": "COCO 1.0"},
          files=files
      )
  ```
</CodeGroup>

### Path Parameters

<ParamField path="id" type="integer" required>
  Unique task identifier
</ParamField>

### Query Parameters

<ParamField query="format" type="string">
  Annotation format (e.g., "COCO 1.0", "YOLO 1.1")
</ParamField>

<ParamField query="filename" type="string">
  Annotation filename (for cloud storage)
</ParamField>

<ParamField query="location" type="string">
  Import location: `local` or `cloud_storage`
</ParamField>

<ParamField query="cloud_storage_id" type="integer">
  Cloud storage ID
</ParamField>

### Response

<ResponseField name="rq_id" type="string">
  Request ID for tracking import status
</ResponseField>

## Update Task Annotations

Update specific annotations (create, update, or delete).

```bash theme={null}
curl -X PATCH "https://app.cvat.ai/api/tasks/{id}/annotations/?action=create" \
  -H "Authorization: Token <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "shapes": [
      {
        "type": "rectangle",
        "frame": 0,
        "label_id": 1,
        "points": [100, 100, 200, 200],
        "attributes": []
      }
    ]
  }'
```

### Path Parameters

<ParamField path="id" type="integer" required>
  Unique task identifier
</ParamField>

### Query Parameters

<ParamField query="action" type="string" required>
  Action to perform: `create`, `update`, or `delete`
</ParamField>

## Replace Task Annotations

Replace all task annotations.

```bash theme={null}
curl -X PUT "https://app.cvat.ai/api/tasks/{id}/annotations/" \
  -H "Authorization: Token <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 0,
    "tags": [],
    "shapes": [],
    "tracks": []
  }'
```

## Delete Task Annotations

Delete all annotations from a task.

```bash theme={null}
curl -X DELETE "https://app.cvat.ai/api/tasks/{id}/annotations/" \
  -H "Authorization: Token <your_token>"
```

## Export Task Dataset

Export task dataset in a specific format.

```bash theme={null}
curl -X POST "https://app.cvat.ai/api/tasks/{id}/dataset/export?format=COCO%201.0&save_images=true" \
  -H "Authorization: Token <your_token>"
```

### Query Parameters

<ParamField query="format" type="string" required>
  Export format name
</ParamField>

<ParamField query="filename" type="string">
  Output filename
</ParamField>

<ParamField query="save_images" type="boolean" default={false}>
  Include images in export
</ParamField>

<ParamField query="location" type="string">
  Export location: `local` or `cloud_storage`
</ParamField>

<ParamField query="cloud_storage_id" type="integer">
  Cloud storage ID
</ParamField>

### Response

<ResponseField name="rq_id" type="string">
  Request ID for tracking export status
</ResponseField>

## Get Task Data Metadata

Retrieve metadata about task media files.

```bash theme={null}
curl -X GET "https://app.cvat.ai/api/tasks/{id}/data/meta" \
  -H "Authorization: Token <your_token>"
```

### Response

<ResponseField name="frames" type="array">
  Array of frame metadata
</ResponseField>

<ResponseField name="size" type="integer">
  Total number of frames
</ResponseField>

<ResponseField name="image_quality" type="integer">
  Image compression quality
</ResponseField>

## Get Task Preview

Retrieve a preview image for a task.

```bash theme={null}
curl -X GET "https://app.cvat.ai/api/tasks/{id}/preview" \
  -H "Authorization: Token <your_token>" \
  --output preview.jpg
```

## Example: Complete Task Workflow

```python theme={null}
import requests
import time

BASE_URL = "https://app.cvat.ai/api"
HEADERS = {"Authorization": "Token <your_token>"}

# Step 1: Create task
task_data = {
    "name": "Traffic Monitoring",
    "project_id": 1,
    "labels": [
        {"name": "vehicle", "color": "#ff0000"},
        {"name": "pedestrian", "color": "#00ff00"}
    ]
}

task = requests.post(
    f"{BASE_URL}/tasks",
    headers=HEADERS,
    json=task_data
).json()
task_id = task["id"]

# Step 2: Upload images
files = [
    ('client_files[0]', open('frame001.jpg', 'rb')),
    ('client_files[1]', open('frame002.jpg', 'rb')),
    ('client_files[2]', open('frame003.jpg', 'rb'))
]

requests.post(
    f"{BASE_URL}/tasks/{task_id}/data",
    headers=HEADERS,
    files=files,
    data={'image_quality': 90}
)

# Step 3: Wait for data processing
time.sleep(5)

# Step 4: Export annotations
export = requests.post(
    f"{BASE_URL}/tasks/{task_id}/dataset/export",
    headers=HEADERS,
    params={"format": "COCO 1.0", "save_images": True}
).json()

rq_id = export["rq_id"]
print(f"Export started: {rq_id}")
```