# 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"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.roboflow.com/developer/rest-api/auto-label.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.