Tasks - CVAT

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.

curl -X GET "https://app.cvat.ai/api/tasks" \
  -H "Authorization: Token <your_token>"

import requests

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

Query Parameters

string

Filter by task name

string

Filter by owner username

string

Filter by assignee username

string

Filter by status: annotation, validation, or completed

integer

Filter by project ID

string

Filter by project name

string

Filter by annotation mode

string

Filter by dimension: 2d or 3d

string

Filter by dataset subset

string

Filter by validation mode: gt or gt_pool

string

Search tasks by multiple fields

string

Sort by field name (prefix with - for descending)

integer

Page number for pagination

integer

Number of results per page

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.

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"
      }
    ]
  }'

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()

Request Body

string

required

Task name

integer

ID of the parent project

array

Array of label definitions (required if not in a project)

integer

User ID of the task owner

integer

User ID of the task assignee

string

Bug tracker URL

string

Dataset subset (train, val, test)

integer

Number of frames per job segment

integer

Frame overlap between segments

object

Source storage configuration

object

Target storage configuration

Response

integer

Task ID

string

Task name

integer

Parent project ID

object

Task owner details

object

Task assignee details

string

Task status: annotation, validation, or completed

array

Array of label definitions

string

Task creation timestamp

string

Task last update timestamp

Get Task Details

Retrieve details of a specific task.

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

Path Parameters

integer

required

Unique task identifier

Update a Task

Update task properties, labels, or move between projects.

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

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()

Path Parameters

integer

required

Unique task identifier

Request Body Examples

Update Task Properties

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

Move Task to Project

{
  "project_id": 10
}

Transfer Task to Organization

{
  "organization_id": 1
}

Delete a Task

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

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

Deleting a task permanently removes all associated jobs, annotations, and uploaded media files.

Path Parameters

integer

required

Unique task identifier

Upload Task Data

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

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"

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"

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
)

Path Parameters

integer

required

Unique task identifier

Form Parameters

array

required

Array of image or video files

integer

default:70

Image compression quality (0-100)

boolean

default:true

Use zip chunks for image sets

integer

Cloud storage ID for remote data

array

Server file paths for server-side data

array

Remote file URLs

Get Task Annotations

Retrieve all annotations for a task.

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

Path Parameters

integer

required

Unique task identifier

Response

integer

Annotation format version

array

Array of image-level tags

array

Array of shape annotations (rectangles, polygons, etc.)

array

Array of tracked objects across frames

Import Task Annotations

Import annotations from a file.

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"

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
    )

Path Parameters

integer

required

Unique task identifier

Query Parameters

string

Annotation format (e.g., “COCO 1.0”, “YOLO 1.1”)

string

Annotation filename (for cloud storage)

string

Import location: local or cloud_storage

integer

Cloud storage ID

Response

string

Request ID for tracking import status

Update Task Annotations

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

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

integer

required

Unique task identifier

Query Parameters

string

required

Action to perform: create, update, or delete

Replace Task Annotations

Replace all task annotations.

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.

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.

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

string

required

Export format name

string

Output filename

boolean

default:false

Include images in export

string

Export location: local or cloud_storage

integer

Cloud storage ID

Response

string

Request ID for tracking export status

Get Task Data Metadata

Retrieve metadata about task media files.

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

Response

array

Array of frame metadata

integer

Total number of frames

integer

Image compression quality

Get Task Preview

Retrieve a preview image for a task.

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

Example: Complete Task Workflow

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

​Overview

​List Tasks

​Query Parameters

​Create a Task

​Request Body

​Response

​Get Task Details

​Path Parameters

​Update a Task

​Path Parameters

​Request Body Examples

​Update Task Properties

​Move Task to Project

​Transfer Task to Organization

​Delete a Task

​Path Parameters

​Upload Task Data

​Path Parameters

​Form Parameters

​Get Task Annotations

​Path Parameters

​Response

​Import Task Annotations

​Path Parameters

​Query Parameters

​Response

​Update Task Annotations

​Path Parameters

​Query Parameters

​Replace Task Annotations

​Delete Task Annotations

​Export Task Dataset

​Query Parameters

​Response

​Get Task Data Metadata

​Response

​Get Task Preview

​Example: Complete Task Workflow

Overview

List Tasks

Query Parameters

Create a Task

Request Body

Response

Get Task Details

Path Parameters

Update a Task

Path Parameters

Request Body Examples

Update Task Properties

Move Task to Project

Transfer Task to Organization

Delete a Task

Path Parameters

Upload Task Data

Path Parameters

Form Parameters

Get Task Annotations

Path Parameters

Response

Import Task Annotations

Path Parameters

Query Parameters

Response

Update Task Annotations

Path Parameters

Query Parameters

Replace Task Annotations

Delete Task Annotations

Export Task Dataset

Query Parameters

Response

Get Task Data Metadata

Response

Get Task Preview

Example: Complete Task Workflow