> 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/developer/rest-api/auto-label.md).

# Auto Label

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](/developer/authentication/scoped-api-keys.md) 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": "<BATCH_ID>",
    "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": "<BATCH_ID>",
    "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"
}
```