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

import requests

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

Query Parameters

integer

Filter by task ID

string

Filter by task name

integer

Filter by project ID

string

Filter by project name

string

Filter by assignee username

string

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

string

Filter by stage: annotation, validation, or acceptance

string

Filter by dimension: 2d or 3d

string

Filter by type: annotation, ground_truth, or consensus_replica

integer

Filter by parent job ID

string

Search jobs by multiple fields

string

Sort by field name

integer

Page number for pagination

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

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": "manual",
    "frames": [1, 5, 10, 18]
  }'

import requests

response = requests.post(
    "https://app.cvat.ai/api/jobs",
    headers={"Authorization": "Token <your_token>"},
    json={
        "type": "ground_truth",
        "task_id": 42,
        "frame_selection_method": "random_uniform",
        "frame_count": 10,
        "random_seed": 1
    }
)
job = response.json()

Request Body

string

required

Job type: annotation, ground_truth, or consensus_replica

integer

required

Parent task ID

string

required

Frame selection method: random_uniform, random_per_job, or manual

integer

Number of frames (for random_uniform method)

Percentage of frames as decimal (for random_uniform method)

integer

Frames per job (for random_per_job method)

Percentage per job as decimal (for random_per_job method)

array

Array of frame numbers (for manual method)

integer

Random seed for reproducibility

Response

integer

Job ID

integer

Parent task ID

integer

Parent project ID

object

Assigned user details

string

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

string

Job stage: annotation, validation, or acceptance

string

Job type

integer

First frame number

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

import requests

response = requests.patch(
    f"https://app.cvat.ai/api/jobs/{job_id}",
    headers={"Authorization": "Token <your_token>"},
    json={
        "state": "in progress",
        "assignee_id": 5
    }
)
updated_job = response.json()

Path Parameters

integer

required

Unique job identifier

Request Body

integer

User ID to assign the job to

string

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

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

integer

Annotation format version

array

Array of image-level tags

array

Array of shape annotations

array

Array of tracked objects

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 "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/jobs/{job_id}/annotations/",
        headers={"Authorization": "Token <your_token>"},
        params={"format": "COCO 1.0"},
        files=files
    )
rq_id = response.json()["rq_id"]

Path Parameters

integer

required

Unique job identifier

Query Parameters

string

Annotation format name

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

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

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

string

required

Data type: frame, chunk, or context_image

integer

Frame or chunk number

integer

Chunk index (for chunk type)

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

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": "manual",
    "honeypot_real_frames": [10, 20, 22]
  }'

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

​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

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