Jobs - CVAT

Overview

Jobs represent individual work units within tasks. Each task is automatically divided into jobs based on the configured segment size. Jobs can be assigned to different annotators for parallel work.

List Jobs

Retrieve a list of all jobs accessible to you.

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

Query Parameters

task_id

integer

Filter by task ID

task_name

string

Filter by task name

project_id

integer

Filter by project ID

project_name

string

Filter by project name

assignee

string

Filter by assignee username

state

string

Filter by state: new, in progress, completed, or rejected

stage

string

Filter by stage: annotation, validation, or acceptance

dimension

string

Filter by dimension: 2d or 3d

type

string

Filter by type: annotation, ground_truth, or consensus_replica

parent_job_id

integer

Filter by parent job ID

string

Search jobs by multiple fields

sort

string

Sort by field name

page

integer

Page number for pagination

page_size

integer

Number of results per page

Create a Job

Create a new job (typically for ground truth or consensus purposes).

curl -X POST "https://app.cvat.ai/api/jobs" \
  -H "Authorization: Token <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "ground_truth",
    "task_id": 42,
    "frame_selection_method": "random_uniform",
    "frame_count": 10,
    "random_seed": 1
  }'

Request Body

type

string

required

Job type: annotation, ground_truth, or consensus_replica

task_id

integer

required

Parent task ID

frame_selection_method

string

required

Frame selection method: random_uniform, random_per_job, or manual

frame_count

integer

Number of frames (for random_uniform method)

Percentage of frames as decimal (for random_uniform method)

frames_per_job_count

integer

Frames per job (for random_per_job method)

Percentage per job as decimal (for random_per_job method)

frames

array

Array of frame numbers (for manual method)

random_seed

integer

Random seed for reproducibility

Response

integer

Job ID

task_id

integer

Parent task ID

project_id

integer

Parent project ID

assignee

object

Assigned user details

state

string

Job state: new, in progress, completed, or rejected

stage

string

Job stage: annotation, validation, or acceptance

type

string

Job type

start_frame

integer

First frame number

stop_frame

integer

Last frame number

Get Job Details

Retrieve details of a specific job.

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

Path Parameters

integer

required

Unique job identifier

Update a Job

Update job properties such as assignee, state, or stage.

curl -X PATCH "https://app.cvat.ai/api/jobs/{id}" \
  -H "Authorization: Token <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "completed",
    "assignee_id": 5
  }'

Path Parameters

integer

required

Unique job identifier

Request Body

assignee_id

integer

User ID to assign the job to

state

string

Job state: new, in progress, completed, or rejected

stage

string

Job stage: annotation, validation, or acceptance

Delete a Job

Delete a job and its annotations. Only certain job types (like ground truth) can be deleted.

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

Not all jobs can be deleted. Currently, only Ground Truth jobs are removable.

Path Parameters

integer

required

Unique job identifier

Get Job Annotations

Retrieve annotations for a specific job.

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

Path Parameters

integer

required

Unique job identifier

Response

version

integer

Annotation format version

Import Job Annotations

Import annotations into a job from a file.

curl -X POST "https://app.cvat.ai/api/jobs/{id}/annotations/?format=COCO%201.0" \
  -H "Authorization: Token <your_token>" \
  -F "[email protected]"

Path Parameters

integer

required

Unique job identifier

Query Parameters

format

string

Annotation format name

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 Job Annotations

Update specific annotations within a job.

curl -X PATCH "https://app.cvat.ai/api/jobs/{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]
      }
    ]
  }'

Path Parameters

integer

required

Unique job identifier

Query Parameters

action

string

required

Action to perform: create, update, or delete

Replace Job Annotations

Replace all annotations in a job.

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

Delete Job Annotations

Delete all annotations from a job.

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

Export Job Dataset

Export a job’s dataset in a specific format.

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

Path Parameters

integer

required

Unique job identifier

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 Job Data

Retrieve media data for a job (frames, chunks, or context images).

curl -X GET "https://app.cvat.ai/api/jobs/{id}/data?type=frame&number=0&quality=original" \
  -H "Authorization: Token <your_token>" \
  --output frame.jpg

Path Parameters

integer

required

Unique job identifier

Query Parameters

type

string

required

Data type: frame, chunk, or context_image

number

integer

Frame or chunk number

index

integer

Chunk index (for chunk type)

quality

string

Quality level: compressed or original

Get Job Data Metadata

Retrieve metadata about job media files.

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

Update Job Data Metadata

Update metadata for job media files.

curl -X PATCH "https://app.cvat.ai/api/jobs/{id}/data/meta" \
  -H "Authorization: Token <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "deleted_frames": [5, 10, 15]
  }'

Get Job Preview

Retrieve a preview image for a job.

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

Get Job Validation Layout

Get the current validation configuration for a job.

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

Update Job Validation Layout

Update validation configuration (honeypot frames).

curl -X PATCH "https://app.cvat.ai/api/jobs/{id}/validation_layout" \
  -H "Authorization: Token <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "frame_selection_method": "random_uniform"
  }'

This operation is not protected from race conditions. Ensure no parallel calls happen.

Example: Job Management Workflow

import requests

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

# Get all jobs for a task
jobs = requests.get(
    f"{BASE_URL}/jobs",
    headers=HEADERS,
    params={"task_id": 42}
).json()["results"]

# Assign jobs to annotators
for i, job in enumerate(jobs):
    annotator_id = (i % 3) + 1  # Round-robin assignment
    requests.patch(
        f"{BASE_URL}/jobs/{job['id']}",
        headers=HEADERS,
        json={
            "assignee_id": annotator_id,
            "state": "in progress"
        }
    )
    print(f"Assigned job {job['id']} to user {annotator_id}")

# Check job progress
for job in jobs:
    job_detail = requests.get(
        f"{BASE_URL}/jobs/{job['id']}",
        headers=HEADERS
    ).json()
    
    print(f"Job {job['id']}: {job_detail['state']} - "
          f"Assignee: {job_detail['assignee']['username']}")

REST API

Python SDK

CLI Tool

​Overview

​List Jobs

​Query Parameters

​Create a Job

​Request Body

​Response

​Get Job Details

​Path Parameters

​Update a Job

​Path Parameters

​Request Body

​Delete a Job

​Path Parameters

​Get Job Annotations

​Path Parameters

​Response

​Import Job Annotations

​Path Parameters

​Query Parameters

​Response

​Update Job Annotations

​Path Parameters

​Query Parameters

​Replace Job Annotations

​Delete Job Annotations

​Export Job Dataset

​Path Parameters

​Query Parameters

​Response

​Get Job Data

​Path Parameters

​Query Parameters

​Get Job Data Metadata

​Update Job Data Metadata

​Get Job Preview

​Get Job Validation Layout

​Update Job Validation Layout

​Example: Job Management Workflow

Build docs developers (and LLMs) love

Overview

List Jobs

Query Parameters

Create a Job

Request Body

Response

Get Job Details

Path Parameters

Update a Job

Path Parameters

Request Body

Delete a Job

Path Parameters

Get Job Annotations

Path Parameters

Response

Import Job Annotations

Path Parameters

Query Parameters

Response

Update Job Annotations

Path Parameters

Query Parameters

Replace Job Annotations

Delete Job Annotations

Export Job Dataset

Path Parameters

Query Parameters

Response

Get Job Data

Path Parameters

Query Parameters

Get Job Data Metadata

Update Job Data Metadata

Get Job Preview

Get Job Validation Layout

Update Job Validation Layout

Example: Job Management Workflow