Manage Annotation Workflow

Use the Python SDK to list upload batches and annotation jobs and assign images to labelers and reviewers.

Python SDK

Project exposes the annotation-pipeline primitives: list the upload batches, inspect annotation jobs, and create new jobs that assign images to a labeler and a reviewer.

List image batches

Every uploaded set of images belongs to a batch. List a project's batches:

import roboflow

rf = roboflow.Roboflow(api_key="YOUR_API_KEY")
project = rf.workspace().project("my-detector")

batches = project.get_batches()
for b in batches.get("batches", []):
    print(b["id"], b["name"], b["images"], "images")

Get a single batch's details:

batch = project.get_batch("<batch-id>")
print(batch)

List annotation jobs

jobs = project.get_annotation_jobs()
for job in jobs.get("jobs", []):
    print(job["id"], job["name"], job["status"], job["annotated"], "/", job["numImages"])

Get a single job:

job = project.get_annotation_job("<job-id>")
print(job)

Create an annotation job

Assign images from a batch to a labeler (and a reviewer, if your workspace has Role-Based Access Control enabled):

job = project.create_annotation_job(
    name="Round 1: indoor frames",
    batch_id="<batch-id>",
    num_images=100,
    labeler_email="[e-mail]",
    reviewer_email="[e-mail]",
)
print(job["id"], job["status"])

Parameters

• name (str) - display name for the job.

• batch_id (str) - id of the upload batch the images come from.

• num_images (int) - how many images from the batch to include in this job.

• labeler_email (str) - email of a workspace member who will draw the labels.

• reviewer_email (str) - email of a workspace member who will review. If RBAC isn't enabled, set this equal to the labeler.

Save an annotation programmatically

When you have annotations from another source (an existing CVAT export, a model prediction you want to commit), use Project.save_annotation to attach them directly to an image.

CLI

You can list annotation batches, inspect batch details, and create annotation jobs from the command line.

Annotation Batches

List Batches

roboflow annotation batch list -p my-project

With JSON output:

roboflow annotation batch list -p my-project --json

Get Batch Details

roboflow annotation batch get <batch-id> -p my-project

roboflow annotation batch get <batch-id> -p my-project --json

Annotation Jobs

List Jobs

roboflow annotation job list -p my-project

roboflow annotation job list -p my-project --json

Get Job Details

roboflow annotation job get <job-id> -p my-project

roboflow annotation job get <job-id> -p my-project --json

Create a Job

roboflow annotation job create -p my-project \
  --name "Label round 1" \
  --batch <batch-id> \
  --num-images 100 \
  --labeler [e-mail] \
  --reviewer [e-mail]

Options

Flag	Description
-p, --project	Project ID (required)
--name	Job name (required)
--batch	Batch ID to draw images from (required)
--num-images	Number of images to include (required)
--labeler	Labeler email address (required)
--reviewer	Reviewer email address (required)

JSON Output

All annotation commands support --json for structured output:

roboflow annotation batch list -p my-project --json | jq '.[].id'
roboflow annotation job create -p my-project --name "Job" \
  --batch abc --num-images 50 --labeler [e-mail] --reviewer [e-mail] --json

Exit codes: 0 = success, 1 = error, 2 = auth error, 3 = not found.