> ## Documentation Index
> Fetch the complete documentation index at: https://avala.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch Auto-Labeling

> Run inference across entire datasets to generate draft annotations automatically

Run SAM or YOLO inference across all unlabeled items in a project to generate draft annotations. Review and refine the results instead of labeling from scratch.

## Overview

Batch auto-labeling takes a project, runs a model against every unlabeled item, and creates draft annotations that annotators can accept, edit, or discard. This dramatically reduces manual labeling time for projects where a pre-trained model can provide a reasonable starting point.

```
Start batch job
      │
      ▼
Fetch unlabeled items
      │
      ▼
Run inference per item ──► Below threshold? → Skip
      │
      ▼
Create draft result
      │
      ▼
Emit webhook event
```

## Quickstart

<CodeGroup>
  ```python Python theme={null}
  import httpx
  import time

  # Start a batch auto-label job
  resp = httpx.post(
      "https://api.avala.ai/api/v1/projects/proj_abc123/auto-label/",
      headers={"X-Avala-Api-Key": "avk_..."},
      json={
          "model_type": "yolo",
          "confidence_threshold": 0.6,
          "dry_run": False,
      },
  )
  job = resp.json()
  print(f"Job started: {job['uid']}")

  # Poll for progress
  while job["status"] in ("pending", "running"):
      time.sleep(5)
      resp = httpx.get(
          f"https://api.avala.ai/api/v1/auto-label-jobs/{job['uid']}/",
          headers={"X-Avala-Api-Key": "avk_..."},
      )
      job = resp.json()
      print(f"Progress: {job['progress_pct']}% ({job['processed_items']}/{job['total_items']})")

  print(f"Done! {job['successful_items']} items labeled, {job['skipped_items']} skipped")
  ```

  ```bash cURL theme={null}
  # Start a batch auto-label job
  curl -X POST https://api.avala.ai/api/v1/projects/proj_abc123/auto-label/ \
    -H "X-Avala-Api-Key: avk_..." \
    -H "Content-Type: application/json" \
    -d '{
      "model_type": "yolo",
      "confidence_threshold": 0.6
    }'

  # Check progress
  curl https://api.avala.ai/api/v1/auto-label-jobs/{job_uid}/ \
    -H "X-Avala-Api-Key: avk_..."

  # List all jobs
  curl https://api.avala.ai/api/v1/auto-label-jobs/?project=proj_abc123 \
    -H "X-Avala-Api-Key: avk_..."

  # Cancel a running job
  curl -X DELETE https://api.avala.ai/api/v1/auto-label-jobs/{job_uid}/ \
    -H "X-Avala-Api-Key: avk_..."
  ```
</CodeGroup>

## API Reference

### Create Job

```
POST /api/v1/projects/{project_uid}/auto-label/
```

| Parameter              | Type       | Default  | Description                                          |
| ---------------------- | ---------- | -------- | ---------------------------------------------------- |
| `model_type`           | `string`   | `"yolo"` | Inference model: `"sam3"` or `"yolo"`.               |
| `confidence_threshold` | `float`    | `0.5`    | Minimum confidence to accept a prediction (0.0-1.0). |
| `labels`               | `string[]` | `[]`     | Filter to specific labels. Empty = all labels.       |
| `dry_run`              | `boolean`  | `false`  | Run inference without creating results.              |

**Response:** `202 Accepted`

```json theme={null}
{
  "uid": "a1b2c3d4-...",
  "status": "pending",
  "model_type": "yolo",
  "confidence_threshold": 0.6,
  "total_items": 0,
  "processed_items": 0,
  "successful_items": 0,
  "failed_items": 0,
  "skipped_items": 0,
  "progress_pct": 0.0,
  "created_at": "2026-02-23T10:30:00Z"
}
```

### Get Job Status

```
GET /api/v1/auto-label-jobs/{uid}/
```

Returns the current state of the job including progress counters.

### List Jobs

```
GET /api/v1/auto-label-jobs/?project={project_uid}&status={status}
```

| Parameter | Type      | Description                                                                 |
| --------- | --------- | --------------------------------------------------------------------------- |
| `project` | `string?` | Filter by project UID.                                                      |
| `status`  | `string?` | Filter by status: `pending`, `running`, `completed`, `failed`, `cancelled`. |

### Cancel Job

```
DELETE /api/v1/auto-label-jobs/{uid}/
```

Cancels a running or pending job. Items already processed are kept.

## Models

### YOLO (Object Detection)

Best for: Detecting and labeling objects with bounding boxes.

* Generates bounding box annotations
* Works well for common object categories
* Fast inference (\~50ms per image)

### SAM (Segmentation)

Best for: Precise object boundaries and segmentation masks.

* Generates segmentation annotations
* Better boundary accuracy than bounding boxes
* Slower inference (\~200ms per image)

## Configuration Guide

### Confidence Threshold

The `confidence_threshold` controls how many predictions are accepted:

| Threshold | Effect                                                      |
| --------- | ----------------------------------------------------------- |
| `0.3`     | More predictions, more noise. Good for initial exploration. |
| `0.5`     | Balanced. Recommended starting point.                       |
| `0.7`     | Fewer predictions, higher quality. Good for production.     |
| `0.9`     | Only very confident predictions. Minimal false positives.   |

### Dry Run

Use `dry_run: true` to preview what the model would label without creating any results:

```bash theme={null}
curl -X POST .../projects/proj_abc123/auto-label/ \
  -H "X-Avala-Api-Key: avk_..." \
  -d '{"model_type": "yolo", "confidence_threshold": 0.5, "dry_run": true}'
```

Check the `successful_items` count to see how many items would be labeled.

## Webhook Events

Auto-label jobs emit webhook events on completion:

| Event                  | Trigger                   |
| ---------------------- | ------------------------- |
| `auto_label.completed` | Job finished successfully |
| `auto_label.failed`    | Job failed with an error  |

```json theme={null}
{
  "event": "auto_label.completed",
  "payload": {
    "job_uid": "a1b2c3d4-...",
    "project_uid": "proj_abc123",
    "status": "completed",
    "total_items": 500,
    "successful": 423,
    "failed": 2,
    "skipped": 75,
    "dry_run": false
  }
}
```

## Limitations

<Warning>
  * Only one auto-label job can run per project at a time
  * Maximum 5,000 items per job
  * Requires a running SageMaker inference endpoint
  * Draft results are attributed to the Avala bot user
  * Only items without existing results are processed
</Warning>

## Next Steps

* [Supported Models](/docs/integrations/supported-models) for details on SAM and YOLO
* [Agent Framework](/docs/integrations/agent-framework) for automated QA after auto-labeling
* [Webhooks](/docs/integrations/webhooks) to trigger pipelines on job completion
* [Inference](/docs/integrations/inference) for single-item interactive inference