> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/datasets/annotate/annotate/manage-annotation-workflow.md).

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

```python
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:

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

### List annotation jobs

```python
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:

```python
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):

```python
job = project.create_annotation_job(
    name="Round 1: indoor frames",
    batch_id="<batch-id>",
    num_images=100,
    labeler_email="labeler@company.com",
    reviewer_email="reviewer@company.com",
)
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`](https://docs.roboflow.com/datasets/manage/manage-images.md#python-sdk) 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

```bash
roboflow annotation batch list -p my-project
```

With JSON output:

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

#### Get Batch Details

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

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

### Annotation Jobs

#### List Jobs

```bash
roboflow annotation job list -p my-project
```

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

#### Get Job Details

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

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

#### Create a Job

```bash
roboflow annotation job create -p my-project \
  --name "Label round 1" \
  --batch <batch-id> \
  --num-images 100 \
  --labeler labeler@company.com \
  --reviewer reviewer@company.com
```

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

```bash
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 a@co.com --reviewer b@co.com --json
```

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

## MCP Server

Connect your AI agent to the [MCP Server](https://docs.roboflow.com/agents/mcp-server) and it can move a labeling job through review with these tools:

<table data-search="false"><thead><tr><th width="290">Tool</th><th>Description</th></tr></thead><tbody><tr><td><code>annotation_jobs_create</code></td><td>Create a job and move images from a batch into it.</td></tr><tr><td><code>annotation_jobs_update</code></td><td>Update a job's labeler, reviewer, or instructions.</td></tr><tr><td><code>annotation_jobs_submit_for_review</code></td><td>Advance a labeling job into review.</td></tr><tr><td><code>annotation_jobs_return_for_edits</code></td><td>Move a review job back to labeling.</td></tr><tr><td><code>annotation_jobs_accept_into_dataset</code></td><td>Finalize job images into the Dataset and assign splits.</td></tr></tbody></table>
