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 with the annotationJob.create and annotationJob.read scopes respectively.

Create an Auto Label Job

To start an auto-label job, make a POST request:

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:

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).
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:

{"a dog": "dog", "a cat": "cat"}

Array of strings - each string is used as both prompt and class name:

["dog", "cat"]

Array of objects:

[{"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

{
    "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:

curl 'https://api.roboflow.com/${WORKSPACE}/autolabel/jobs/${JOB_ID}?api_key=${ROBOFLOW_API_KEY}'

Use the jobId returned from the create endpoint.

Response

{
    "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"
}