> 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/ai-labeling/auto-label.md).
# Auto Label
## About
{% hint style="info" %}
Auto Label is one of many [AI Labeling](/datasets/annotate/annotate/ai-labeling.md) features. Using this feature will consume [credits](https://docs.roboflow.com/platform/billing-and-plans/credits) at the rates listed on our [credits page](https://roboflow.com/credits).
{% endhint %}
Roboflow Auto Label lets you use a foundation vision model (SAM 3), Roboflow trained models, or a saved [Workflow](https://docs.roboflow.com/workflows) to automatically label images.
Roboflow Auto Label can use the following sources to identify the objects you specify:
* SAM 3 - a foundation model that labels objects from text prompts (object detection and segmentation)
* Models trained in Roboflow ([https://github.com/roboflow/docs/tree/main/models/README.md](https://github.com/roboflow/docs/tree/main/models/README.md "mention"))
* Note: Only models from the same dataset as your Annotation Batch are currently supported.
* A saved [Workflow](https://docs.roboflow.com/workflows) compatible with your project type
Auto Label has been used to label millions of images for use in training computer vision models.
If you would rather auto-label on your own hardware, Roboflow also maintains [Autodistill](https://github.com/autodistill/autodistill), an open source framework for auto-labeling image datasets with a range of foundation models.
### When to Use Roboflow Auto Label
You should use Roboflow Auto Label if you need to annotate common objects such as vehicles (i.e. forklifts), people, generic defects (i.e. cracks), and generic products (i.e. vinyl records, bread).
You should not use a foundation model like SAM 3 if you need to identify specific variants of an object. For example, Auto Label cannot distinguish between different types of crack, or identify unique defects in electronics.
## Label Data with Roboflow Auto Label
The Roboflow platform lets you preview how Auto Label will perform on labeling classes of data in your dataset before you run a job on your full batch. After labeling, you can review the results for quality assurance (recommended) and train a model on the labeled dataset.
### Step #1: Upload Data
First, upload data to Roboflow. See our [Upload Images, Videos, and Annotations](/datasets/create-and-upload/adding-data.md) instructions for more information.
Uploading images into Roboflow.
### Step #2: Enter Auto Label
Once you have uploaded all of your images, you will be asked how you want to label your images. Select "Auto-Label And Review".
Select "Auto-Label And Review" to open the Roboflow Auto Label interface.
### Step #3: Configure Auto Label
The Auto Label labeling interface will appear in which you can configure your auto labeling job.
#### Classes (& Descriptions)
Classes represent the labels you want to assign to objects in the image. Descriptions represent a visual description of the class that the foundation model (SAM 3) will use to identify instances of those classes. By default, the description will be the class name.
Auto Label works best when labeling common objects with clear visual descriptions. For example, Auto Label will be able to identify the location of an aluminum can on a production line. But, Auto Label will be unable to label images according to specific requirements, such as distinguishing the brand of an aluminum can.
#### Generating Test Results
Once you have configured Auto Label, click "Generate Test Results" to test your classes on a small subset of your dataset. By default, four images are selected.
The Auto Label interface.
### Step #4: Evaluate Roboflow Auto Label Labels
Here are the test results when using the class "aluminum can" on an example image. From here, you can:
Auto Label annotating aluminum cans.
#### Adjust your classes & descriptions
If Auto Label doesn't label images as expected, try testing different descriptions for your classes.
{% hint style="info" %}
All test results are free & don't use any credits.
{% endhint %}
#### Adjust the confidence
The number to the right of each class is represented as (boxes of this class that are shown) / (total boxes of this class). You can adjust the confidence threshold of each class to filter out more or less boxes. Higher confidence means less boxes will be shown.
{% hint style="info" %}
The confidence threshold set here will be the same one used when labeling the entire batch, so make sure it looks right!
{% endhint %}
#### Test on different images
To review Auto Label's performance on different images from your batch, click on an image in the "Test images" section on the bottom left. The preview for that image should load immediately without pressing additional buttons.
## Label with a Workflow
Instead of a foundation or trained model, you can auto-label with a saved [Workflow](https://docs.roboflow.com/workflows), letting you use SAHI, model ensembles, and multi-step custom logic to label your batch.
In the Auto Label model dropdown, open the "Workflows" tab and select a workflow. Only workflows compatible with your project type (detection, segmentation, or classification) are listed.
After selecting a workflow, map each of its output classes to a class in your project and set a per-class confidence threshold. A preview runs on sample images so you can confirm the mapping before starting the job.
{% hint style="info" %}
Only the classes you map are applied. Output classes with no mapping are dropped, so map every class you want written back to your project.
{% endhint %}
When the mapping looks right, click "Auto Label With This Workflow" to start the job. It runs in the background and applies the mapped labels to your batch.
### Run Auto Label On Your Batch
If Auto Label labels your images as you expect, click "Auto Label with This Model". Review the summary modal, and click to proceed. It should take a few minutes to label a thousand images.
Once the job starts, you are taken to the Annotate page, where the new Auto Label job is listed alongside your other annotation jobs. Auto Label runs in the background, so you can review results there when it finishes.
## HTTP API
You can programmatically start and track auto-labeling jobs using the REST API. Auto Label uses foundation models (SAM 3) or your own trained Roboflow models to automatically annotate images in a batch.
These endpoints require [scoped API keys](https://docs.roboflow.com/reference/authentication/authentication/scoped-api-keys) with the `annotationJob.create` and `annotationJob.read` scopes respectively.
### Create an Auto Label Job
To start an auto-label job, make a POST request:
```bash
curl --location --request POST 'https://api.roboflow.com/${WORKSPACE}/${PROJECT}/autolabel?api_key=${ROBOFLOW_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"batchId": "",
"modelType": "sam3",
"ontology": {"a dog": "dog", "a cat": "cat"}
}'
```
You can also omit `ontology` to let the API derive it from your model or dataset classes:
```bash
curl --location --request POST 'https://api.roboflow.com/${WORKSPACE}/${PROJECT}/autolabel?api_key=${ROBOFLOW_API_KEY}' \
--header 'Content-Type: application/json' \
--data-raw '{
"batchId": "",
"modelType": "sam3"
}'
```
#### Request Body
| Parameter | Type | Required | Description |
| ---------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `batchId` | string | Yes | The ID of the image batch to label. |
| `modelType` | string | Yes | Model to use. One of: `sam3`, `custom_roboflow`. |
| `ontology` | object or array | No | Maps prompts to class names. See formats below. When omitted, derived automatically (see [Ontology Auto-Derivation](#ontology-auto-derivation)). |
| `numImagesToLabel` | number | No | Number of images to label. Defaults to the full batch. |
| `defaultConfidence` | number | No | Confidence threshold applied to all classes (0-1). |
| `confidenceThresholds` | object | No | Per-class confidence thresholds, e.g. `{"dog": 0.5, "cat": 0.7}`. |
| `reviewerEmail` | string | No | Email of a workspace member to assign as reviewer. Defaults to the workspace owner. |
| `runNMS` | boolean | No | Whether to run non-max suppression. Defaults to `true`. |
| `modelOptions` | object | No | Additional model-specific options (e.g. `{"modelId": "your-model/1"}` for `custom_roboflow`). |
#### Ontology Formats
The `ontology` field accepts several formats. All are normalized internally.
**Object (canonical)** - keys are prompts, values are class names:
```json
{"a dog": "dog", "a cat": "cat"}
```
**Array of strings** - each string is used as both prompt and class name:
```json
["dog", "cat"]
```
**Array of objects:**
```json
[{"class": "dog", "prompt": "a dog"}, {"class": "cat", "prompt": "a cat"}]
```
#### Ontology Auto-Derivation
When `ontology` is omitted (or empty), the API will attempt to derive it automatically based on the `modelType`:
| Model Type | Derivation Source |
| ----------------- | ---------------------------------------------------------------------------- |
| `custom_roboflow` | Uses the trained classes from the model specified in `modelOptions.modelId`. |
| `sam3` | Uses the class names defined in the dataset. |
If the dataset has locked annotation classes, the derived ontology is intersected with the allowed classes so no invalid annotations are produced.
The request will fail with a `400` if the ontology cannot be derived, for example when the dataset has no classes or the model classes don't overlap with the dataset's locked classes. Possible `errorType` values:
* `MISSING_MODEL_ID` - `modelOptions.modelId` is required for `custom_roboflow` when ontology is not provided.
* `MODEL_CLASSES_UNAVAILABLE` - The specified model has no classes.
* `NO_MATCHING_CLASSES` - The model's classes don't overlap with the dataset's locked classes.
* `DATASET_HAS_NO_CLASSES` - The dataset has no classes defined (for `sam3`).
#### Response
```json
{
"jobId": "auto-label-job-uuid",
"annotationJobId": "annotation-job-uuid",
"message": "Automatic labeling job created"
}
```
### Get Auto Label Job Status
To check the progress of an auto-label job, make a GET request:
```bash
curl 'https://api.roboflow.com/${WORKSPACE}/autolabel/jobs/${JOB_ID}?api_key=${ROBOFLOW_API_KEY}'
```
Use the `jobId` returned from the create endpoint.
#### Response
```json
{
"id": "auto-label-job-uuid",
"status": "pending",
"modelType": "sam3",
"projectType": "object-detection",
"projectId": "project-id",
"annotationJobId": "annotation-job-uuid",
"numImages": 100,
"numImagesSentBack": 0,
"subjobs": [
{"id": "subjob-1", "status": "pending"},
{"id": "subjob-2", "status": "done"}
],
"ontology": {"a dog": "dog"},
"confidenceThresholds": {"dog": 0.5},
"startTime": "2026-01-01T00:00:00.000Z"
}
```