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

Query Parameters

name

string

Filter by task name

owner

string

Filter by owner username

assignee

string

Filter by assignee username

status

string

Filter by status: annotation, validation, or completed

project_id

integer

Filter by project ID

project_name

string

Filter by project name

mode

string

Filter by annotation mode

dimension

string

Filter by dimension: 2d or 3d

subset

string

Filter by dataset subset

validation_mode

string

Filter by validation mode: gt or gt_pool

string

Search tasks by multiple fields

sort

string

Sort by field name (prefix with - for descending)

page

integer

Page number for pagination

page_size

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

Request Body

name

string

required

Task name

project_id

integer

ID of the parent project

labels

array

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

owner_id

integer

User ID of the task owner

assignee_id

integer

User ID of the task assignee

bug_tracker

string

Bug tracker URL

subset

string

Dataset subset (train, val, test)

segment_size

integer

Number of frames per job segment

overlap

integer

Frame overlap between segments

source_storage

object

Source storage configuration

target_storage

object

Target storage configuration

Response

integer

Task ID

name

string

Task name

project_id

integer

Parent project ID

owner

object

Task owner details

assignee

object

Task assignee details

status

string

Task status: annotation, validation, or completed

labels

array

Array of label definitions

created_date

string

Task creation timestamp

updated_date

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

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][email protected]" \
  -F "client_files[1][email protected]" \
  -F "client_files[2][email protected]"

Path Parameters

integer

required

Unique task identifier

Form Parameters

client_files

array

required

Array of image or video files

image_quality

integer

default:70

Image compression quality (0-100)

use_zip_chunks

boolean

default:true

Use zip chunks for image sets

cloud_storage_id

integer

Cloud storage ID for remote data

server_files

array

Server file paths for server-side data

remote_files

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

version

integer

Annotation format version

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 "[email protected]"

Path Parameters

integer

required

Unique task identifier

Query Parameters

format

string

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

filename

string

Annotation filename (for cloud storage)

location

string

Import location: local or cloud_storage

cloud_storage_id

integer

Cloud storage ID

Response

rq_id

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

action

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

format

string

required

Export format name

filename

string

Output filename

save_images

boolean

default:false

Include images in export

location

string

Export location: local or cloud_storage

cloud_storage_id

integer

Cloud storage ID

Response

rq_id

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

frames

array

Array of frame metadata

size

integer

Total number of frames

image_quality

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

REST API

Python SDK

CLI Tool

​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

Build docs developers (and LLMs) love

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