> 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/team-collaboration.md).

# Collaborate on Labeling

Have the entire team help label your datasets.

## About

Whether you have a small team working on labeling hundreds of images or a large team working on millions, creating a dataset is about more than drawing boxes. A big part of labeling is in the process of getting an image from the real world into a trained model's stored knowledge that involves image collection, storage, organization, selection, assignment, labeling, and review.

Roboflow offers collaborative features that allow you to:

* Divide work between multiple team members by assigning labeling jobs to anyone on the team
* Organize images into batches as you upload them
* Provide image labeling instructions to help guide work and ensure consistency
* Get an at-a-glance view of labeling work in progress
* See a historical timeline of all labeling work
* Revert changes
* Add comments to images and view image comment history
* Send images with labeling issues back to team members for changes
* Approve or reject labels before including them in a dataset

### Assign Labeling Jobs

You can divide labeling work among a team or assign it to specific people responsible for labeling. Assigning jobs to individual team members means you won't have to worry about stepping on each others' work if you're online at the same time.

<figure><img src="https://2252499186-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-3d03f750bc80afa125f9c70dfdfe5c2ede3f0e88%2FScreenshot%202025-06-27%20at%2015.58.55.png?alt=media" alt=""><figcaption></figcaption></figure>

You can choose to assign jobs to one or more people on your team and if you haven’t included a team member to your workspace yet, you can also [invite them](https://docs.roboflow.com/platform/workspaces/team-members/invite-a-team-member) and assign an labeling job to be completed at the same time.

### **Provide** Labeling Instructions

You can provide instructions to labelers from the Assign Images tab. Click "Add Instructions" to add instructions to a batch before assigning the batch to an labeler. When you have set your instructions, click "Assign Images".

<figure><img src="https://2252499186-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-9425465335ac442051fe5f8b66d8a2b95069e1a1%2FScreenshot%202025-06-27%20at%2016.00.33.png?alt=media" alt=""><figcaption></figcaption></figure>

Click "Edit" to assign instructions:

<figure><img src="https://2252499186-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-208d4f5de293fdaece24a1e0439b313660ab9b1d%2FScreenshot%202025-06-27%20at%2016.09.22.png?alt=media" alt=""><figcaption></figcaption></figure>

Click "Save Instructions" to save the labeling instructions.

### Job Notifications

Once a labeling job has been assigned, a notification will alert your team members when there's work assigned to them.

### Labeling Jobs Board

The labeling jobs board gives an at-a-glance view of the current state of your individually assigned jobs as they go through the labeling process.

<figure><img src="https://2252499186-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-763594df65168569a56cfe229cd094d0f4cf9b2a%2FScreenshot%202025-06-27%20at%2016.04.23.png?alt=media" alt=""><figcaption></figcaption></figure>

To view statistics for a particular labeler, specify a value in the `Labeler` dropdown.

### Job Details

Clicking on individual jobs on the labeling jobs board gives a more detailed view of the individual job and its progress. You can quickly see images that still need to be labeled and reassign jobs to different team members as needed.

<figure><img src="https://2252499186-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-6ed68f7f7521a5de9a7e9e63bcb97dd3e3ca8342%2FScreenshot%202025-06-27%20at%2016.05.41.png?alt=media" alt=""><figcaption></figcaption></figure>

#### Managing Individual Images

On the Annotated tab within a job, you can select individual images using checkboxes, drag-to-select, or the "Select all" checkbox in the header. Once you have a selection:

* Click "Send N Images to Unannotated" to move selected images back to the Unannotated tab for re-labeling.
* Click "Add N Images to Dataset" to add only the selected images to the dataset. Unselected annotated images remain in the job.

When adding a partial selection to the dataset, the job stays in its current state with updated counts so labelers can continue working on the remaining images.

These controls are also available in the annotation editor. When viewing an annotated image in an assigned job:

* Use the checkmark button to add the current image to the dataset.
* Use the "Send to Unannotated" button (arrow icon) next to the image switcher to send the current image back for re-labeling.

After either action, the editor advances to the next image automatically.

### Review Mode

You can individually approve or reject labeled images and send them back to the labeler for rework when necessary. To do so, click on a batch of images. Then, navigate between the Approved, Rejected, and To Do tabs to view the state of images in a job.

<figure><img src="https://2252499186-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNVfRxNsvCh4GOyqrjmzX%2Fuploads%2Fgit-blob-dc9c04eb0d0d59159e8281aec2a6c94477c755ea%2FScreenshot%202025-06-27%20at%2016.06.07.png?alt=media" alt=""><figcaption></figcaption></figure>

Review Mode is on if your plan includes it, and it applies to every project in the workspace. To turn it off, go to Settings, open "Project Settings", and switch off "Review Mode". This removes the Review column, so a finished job goes straight to your Dataset. You can switch it back on at any time, since turning it off does not remove Review Mode from your plan.

You need the Edit Workspace Settings permission to change it. If batches are still in review when you turn it off, Roboflow asks you to confirm, then moves those batches back to Annotating.

### Browse Labeling Work From the Agent

Open a project tab in [Roboflow Agent](https://docs.roboflow.com/agents/roboflow-agent) and select "Dataset" to browse the project's images by labeling stage. A chip per stage ("Unassigned", "Annotating", "Review", "Dataset") shows its image count. Pick a chip, then a batch or job card, to narrow the grid below.

Click an image to open it in the annotation editor. Images open read-only in "Unassigned", or when the job has left the annotation board or is no longer assigned to you. You need the Search Workspace Images permission, plus Update Annotation to edit labels.

#### Move a Job Through Its Stages

When you open a job in the Agent, the tab bar shows where the job sits: "Unassigned", "Annotating", "Review", or "Dataset". Hover over a step to read what happens in that stage. If [Review Mode](#review-mode) is switched off for your workspace, the "Review" step is greyed out. If your plan does not include it, the step offers a way to upgrade.

Buttons beside the stepper move the job forward or back. Which ones you see depends on the stage and your permissions:

* "Move N to Annotating" creates a labeling job from unassigned images and assigns it to you.
* "Submit for Review" sends a job that is being annotated to review.
* "Move Back to Annotating" sends every image in a job under review back for more labeling.
* "Add N to Dataset" adds the job's ready images to the dataset. If you add only some of them, the rest stay in the job.

Each button re-checks the job's stage before it writes. If someone else moved the job in the meantime, nothing changes and the Agent tells you why.

#### Add Images and Start Annotating

Ask the Agent to add images from your workspace to a model and start labeling them. It adds the images, assigns them to a labeling job with you as the labeler, and opens the annotation editor on that job.

This mode takes up to 500 images per request and works with images only. Adding images without labeling them has no such limit. Action Recognition and Multimodal projects are not supported.

The work runs in the background. If the job cannot be created (ex: some of the images are already in another job), the images are still added to the model, no job is created, and the Agent tells you what stopped the assignment.

#### Approve and Reject Images

When the job you opened is in the "Review" stage, the editor shows the same approve and reject controls as the annotation board. Click "Approve" or "Reject" on the current image, or press A to approve, R to reject, and U to undo your last decision. This needs the Review Image permission.

## HTTP API

You can use the jobs endpoint to get info about your annotation jobs, their current status or assign images for labeling by creating a new Annotation Job with images from one of your batches.

### Create a New Annotation Job

{% hint style="warning" %}
**You need to set both reviewer and labeler to an email that belong to a user in your workspace.**

If your workspace does not have Role Based Access Control enabled, you won't see the reviewer in the app interface, and should set the reviewer to the same user as the labeler.
{% endhint %}

You can make a POST request to the /jobs endpoint of your project to create a new Annotation Job in your project. To create a new job the you need to provide some JSON encoded data in the body of your POST request.

To create a new Annotation Job in a project, that assigns 10 images from one of the batches in the project to be annotated by <lenny@roboflow.com> you can make a POST request like this:

```bash
curl --location --request POST 'https://api.roboflow.com/${WORKSPACE}/${PROJECT}/jobs?api_key=${ROBOFLOW_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Job created by API",
    "batch": "<BATCH_ID>",
    "num_images": 10,
    "labelerEmail": "lenny@roboflow.com",
    "reviewerEmail": "lenny@roboflow.com"
}'
```

This request returns the following data:

```json
{
    "created": {
        "_seconds": 1669234345,
        "_nanoseconds": 61000000
    },
    "rejected": 0,
    "annotated": 0,
    "numImages": 2,
    "createdBy": "API",
    "owner": "holeSv3hwbzrOv37vH5b",
    "instructionsText": "No instructions provided",
    "unannotated": 2,
    "reviewer": "thomas@roboflow.com",
    "labeler": "korryn@roboflow.com",
    "name": "API Job 1",
    "project": "PBDhem3YRI1rKtQZSqRK",
    "approved": 0,
    "status": "assigned",
    "sourceBatch": "PBDhem3YRI1rKtQZSqRK/6VN0fFQIWU1E24bDjGsN",
    "id": "0IzntY4ms4ogwHwJNkIB"
}
```

### Retrieve Annotation Job Data from the API

To retrieve annotation job data from the REST API, make a request to the following endpoint:

```bash
curl https://api.roboflow.com/${WORKSPACE}/${PROJECT}/jobs?api_key=${ROBOFLOW_API_KEY}
```

This will return data in the following format:

```json
{
    "jobs": [
        {
            "owner": "holeSv3hwbzrOv37vH5b",
            "approved": 0,
            "createdBy": "g12lCVib0pgurZ6EqWLnApJJ4gr1",
            "sourceBatch": "PBDhem3YRI1rKtQZSqRK/6VN0fFQIWU1E24bDjGsN",
            "annotated": 3,
            "rejected": 0,
            "labeler": "thomas@roboflow.com",
            "numImages": 26,
            "status": "assigned",
            "instructionsText": "",
            "name": "Uploaded on 11/22/22 at 1:39 pm: Job 9",
            "reviewer": "thomas@roboflow.com",
            "created": {
                "_seconds": 1669148088,
                "_nanoseconds": 297000000
            },
            "project": "PBDhem3YRI1rKtQZSqRK",
            "unannotated": 23,
            "id": "5LfYNJg10Z9Kvx5Tt5Uq"
        },

        {
            "approved": 0,
            "unannotated": 2,
            "instructionsText": "Please label all the racoons in the images using polygons",
            "annotated": 12,
            "sourceBatch": "PBDhem3YRI1rKtQZSqRK/6VN0fFQIWU1E24bDjGsN",
            "project": "PBDhem3YRI1rKtQZSqRK",
            "rejected": 0,
            "owner": "holeSv3hwbzrOv37vH5b",
            "createdBy": "API",
            "status": "assigned",
            "created": {
                "_seconds": 1669148192,
                "_nanoseconds": 651000000
            },
            "labeler": "korryn@roboflow.com",
            "name": "Test Job",
            "numImages": 25,
            "reviewer": "thomas@roboflow.com",
            "id": "h2E42jt686yLyMIxxqOQ"
        }
    ]
}
```

To retrieve information about a specific job, specify the job ID:

```bash
curl https://api.roboflow.com/${WORKSPACE}/${PROJECT}/jobs/${JOB_ID}?api_key=${ROBOFLOW_API_KEY}
```

Here is the response format from this request:

```json
{
    "approved": 0,
    "unannotated": 2,
    "instructionsText": "Please label all the racoons in the images using polygons",
    "annotated": 12,
    "sourceBatch": "PBDhem3YRI1rKtQZSqRK/6VN0fFQIWU1E24bDjGsN",
    "project": "PBDhem3YRI1rKtQZSqRK",
    "rejected": 0,
    "owner": "holeSv3hwbzrOv37vH5b",
    "createdBy": "API",
    "status": "assigned",
    "created": {
        "_seconds": 1669148192,
        "_nanoseconds": 651000000
    },
    "labeler": "korryn@roboflow.com",
    "name": "Test Job",
    "numImages": 25,
    "reviewer": "thomas@roboflow.com",
    "id": "<JOB_ID>"
}
```

## Python SDK

### Create a New Annotation Job

To create an annotation job, you will need an upload batch that you would like to assign to a labeler and a reviewer:

```python
import roboflow

rf = roboflow.Roboflow(api_key="YOUR_API_KEY")

project = rf.workspace().project("PROJECT_ID")

job = project.create_annotation_job(
    name="Test Annotation Job",
    batch_id=UPLOAD_BATCH_ID,
    num_images=UPLOAD_BATCH_SIZE,
    labeler_email="test@example.com",
    reviewer_email="test@example.com",
)
```

## MCP Server

Connect your AI agent to the [MCP Server](https://docs.roboflow.com/agents/mcp-server) and it can assign labeling work to your team 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_list</code></td><td>List annotation jobs in a project.</td></tr><tr><td><code>annotation_jobs_get</code></td><td>Get details about one annotation job.</td></tr><tr><td><code>annotation_jobs_create</code></td><td>Create a job and assign images to a labeler and reviewer.</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_images_reassign</code></td><td>Create a job from selected images and clear their prior assignment.</td></tr></tbody></table>