> ## 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.

# Models

> API reference for ML model integrations and predictions

List available ML models, manage integrations, run predictions, and retrieve results.

<Tip>
  Models in Avala are pre-configured machine learning models (e.g., object detection, segmentation) that can generate predictions on your dataset items. Each model has one or more **integrations** that connect it to a provider endpoint. Predictions are created by initiating a **run** against an integration.
</Tip>

## List Models

```
GET /api/v1/models/
```

Returns all available ML models, ordered by most recent first.

### Parameters

| Name     | Type    | Required | Description                                  |
| -------- | ------- | -------- | -------------------------------------------- |
| `cursor` | string  | No       | Cursor for pagination (query parameter)      |
| `limit`  | integer | No       | Number of results per page (query parameter) |

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.avala.ai/api/v1/models/" \
    -H "X-Avala-Api-Key: $AVALA_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.avala.ai/api/v1/models/",
      headers={"X-Avala-Api-Key": "YOUR_API_KEY"}
  )
  models = response.json()["results"]
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api.avala.ai/api/v1/models/",
    {
      headers: { "X-Avala-Api-Key": "YOUR_API_KEY" },
    }
  );
  const { results } = await response.json();
  ```

  ```go Go theme={null}
  req, _ := http.NewRequest("GET", "https://api.avala.ai/api/v1/models/", nil)
  req.Header.Set("X-Avala-Api-Key", "YOUR_API_KEY")

  resp, err := http.DefaultClient.Do(req)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "next": null,
  "previous": null,
  "results": [
    {
      "uid": "d1e2f3a4-b5c6-7d8e-9f0a-1b2c3d4e5f6a",
      "name": "Segment Anything Model",
      "description": "Foundation model for image segmentation",
      "model_type_name": "segmentation",
      "model_type_description": "Instance and semantic segmentation",
      "is_public": true,
      "created_at": "2024-09-01T12:00:00Z",
      "updated_at": "2024-09-01T12:00:00Z"
    }
  ]
}
```

### Fields

| Field                    | Type              | Description                                                |
| ------------------------ | ----------------- | ---------------------------------------------------------- |
| `uid`                    | string (UUID)     | Unique identifier for the model                            |
| `name`                   | string            | Display name of the model                                  |
| `description`            | string            | Human-readable description of the model                    |
| `model_type_name`        | string            | Name of the model type (e.g., `segmentation`, `detection`) |
| `model_type_description` | string            | Description of the model type                              |
| `is_public`              | boolean           | Whether this model is publicly available                   |
| `created_at`             | string (datetime) | ISO 8601 timestamp of creation                             |
| `updated_at`             | string (datetime) | ISO 8601 timestamp of the last update                      |

***

## List Integrations

```
GET /api/v1/models/{model_uid}/integrations/
```

Returns all active integrations (provider configurations) for a specific model.

### Parameters

| Name        | Type          | Required | Description                                  |
| ----------- | ------------- | -------- | -------------------------------------------- |
| `model_uid` | string (UUID) | Yes      | Model UID (path parameter)                   |
| `cursor`    | string        | No       | Cursor for pagination (query parameter)      |
| `limit`     | integer       | No       | Number of results per page (query parameter) |

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.avala.ai/api/v1/models/d1e2f3a4-b5c6-7d8e-9f0a-1b2c3d4e5f6a/integrations/" \
    -H "X-Avala-Api-Key: $AVALA_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.avala.ai/api/v1/models/d1e2f3a4-b5c6-7d8e-9f0a-1b2c3d4e5f6a/integrations/",
      headers={"X-Avala-Api-Key": "YOUR_API_KEY"}
  )
  integrations = response.json()["results"]
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api.avala.ai/api/v1/models/d1e2f3a4-b5c6-7d8e-9f0a-1b2c3d4e5f6a/integrations/",
    {
      headers: { "X-Avala-Api-Key": "YOUR_API_KEY" },
    }
  );
  const { results } = await response.json();
  ```

  ```go Go theme={null}
  req, _ := http.NewRequest("GET", "https://api.avala.ai/api/v1/models/d1e2f3a4-b5c6-7d8e-9f0a-1b2c3d4e5f6a/integrations/", nil)
  req.Header.Set("X-Avala-Api-Key", "YOUR_API_KEY")

  resp, err := http.DefaultClient.Do(req)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "next": null,
  "previous": null,
  "results": [
    {
      "uid": "e2f3a4b5-c6d7-8e9f-0a1b-2c3d4e5f6a7b",
      "created_at": "2024-09-15T10:00:00Z",
      "updated_at": "2024-09-15T10:00:00Z",
      "provider_name": "AWS SageMaker",
      "provider_config_type": "real-time",
      "provider_config_uid": "f3a4b5c6-d7e8-9f0a-1b2c-3d4e5f6a7b8c",
      "provider_config_name": "SAM Endpoint (us-west-2)"
    }
  ]
}
```

### Integration Fields

| Field                  | Type              | Description                                              |
| ---------------------- | ----------------- | -------------------------------------------------------- |
| `uid`                  | string (UUID)     | Unique identifier for the integration                    |
| `provider_name`        | string            | Name of the provider (e.g., `AWS SageMaker`)             |
| `provider_config_type` | string            | Type of the provider config (e.g., `real-time`, `batch`) |
| `provider_config_uid`  | string (UUID)     | UID of the underlying provider configuration             |
| `provider_config_name` | string            | Display name of the provider configuration               |
| `created_at`           | string (datetime) | ISO 8601 timestamp of creation                           |
| `updated_at`           | string (datetime) | ISO 8601 timestamp of the last update                    |

***

## Create Prediction Run

```
POST /api/v1/models/integrations/{integration_uid}/predict/
```

Initiates a prediction run against a model integration. You can run predictions on an entire dataset or a subset of items. Predictions are processed asynchronously.

### Parameters

| Name              | Type          | Required | Description                      |
| ----------------- | ------------- | -------- | -------------------------------- |
| `integration_uid` | string (UUID) | Yes      | Integration UID (path parameter) |

The request body is an array of objects, each specifying a dataset and optionally specific items:

| Name                | Type          | Required | Description                                                 |
| ------------------- | ------------- | -------- | ----------------------------------------------------------- |
| `dataset_uid`       | string (UUID) | Yes      | Dataset to run predictions on                               |
| `dataset_item_uids` | array         | Yes      | Item UIDs within the dataset (empty array for full dataset) |

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.avala.ai/api/v1/models/integrations/e2f3a4b5-c6d7-8e9f-0a1b-2c3d4e5f6a7b/predict/" \
    -H "X-Avala-Api-Key: $AVALA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '[
      {
        "dataset_uid": "550e8400-e29b-41d4-a716-446655440000",
        "dataset_item_uids": [
          "660f9500-f30c-52e5-b827-557766551111",
          "771a0600-a41d-63f6-c938-668877662222"
        ]
      }
    ]'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.avala.ai/api/v1/models/integrations/e2f3a4b5-c6d7-8e9f-0a1b-2c3d4e5f6a7b/predict/",
      headers={
          "X-Avala-Api-Key": "YOUR_API_KEY",
          "Content-Type": "application/json"
      },
      json=[
          {
              "dataset_uid": "550e8400-e29b-41d4-a716-446655440000",
              "dataset_item_uids": [
                  "660f9500-f30c-52e5-b827-557766551111",
                  "771a0600-a41d-63f6-c938-668877662222"
              ]
          }
      ]
  )
  runs = response.json()
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api.avala.ai/api/v1/models/integrations/e2f3a4b5-c6d7-8e9f-0a1b-2c3d4e5f6a7b/predict/",
    {
      method: "POST",
      headers: {
        "X-Avala-Api-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify([
        {
          dataset_uid: "550e8400-e29b-41d4-a716-446655440000",
          dataset_item_uids: [
            "660f9500-f30c-52e5-b827-557766551111",
            "771a0600-a41d-63f6-c938-668877662222",
          ],
        },
      ]),
    }
  );
  const runs = await response.json();
  ```

  ```go Go theme={null}
  body := strings.NewReader(`[
      {
          "dataset_uid": "550e8400-e29b-41d4-a716-446655440000",
          "dataset_item_uids": [
              "660f9500-f30c-52e5-b827-557766551111",
              "771a0600-a41d-63f6-c938-668877662222"
          ]
      }
  ]`)

  req, _ := http.NewRequest("POST", "https://api.avala.ai/api/v1/models/integrations/e2f3a4b5-c6d7-8e9f-0a1b-2c3d4e5f6a7b/predict/", body)
  req.Header.Set("X-Avala-Api-Key", "YOUR_API_KEY")
  req.Header.Set("Content-Type", "application/json")

  resp, err := http.DefaultClient.Do(req)
  ```
</CodeGroup>

### Response

```json theme={null}
[
  {
    "uid": "a4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d",
    "run_status": "pending",
    "type": "partial",
    "integration_uid": "e2f3a4b5-c6d7-8e9f-0a1b-2c3d4e5f6a7b",
    "dataset": [
      {
        "dataset_uid": "550e8400-e29b-41d4-a716-446655440000",
        "dataset_item_uids": [
          "660f9500-f30c-52e5-b827-557766551111",
          "771a0600-a41d-63f6-c938-668877662222"
        ]
      }
    ],
    "created_at": "2025-03-15T10:00:00Z",
    "updated_at": "2025-03-15T10:00:00Z"
  }
]
```

***

## List Runs

```
GET /api/v1/models/runs/
```

Returns all prediction runs for the authenticated user, ordered by most recent first.

### Parameters

| Name               | Type          | Required | Description                                  |
| ------------------ | ------------- | -------- | -------------------------------------------- |
| `integration_uid`  | string (UUID) | No       | Filter by integration (query parameter)      |
| `run_status`       | string        | No       | Filter by status (query parameter)           |
| `dataset_uid`      | string (UUID) | No       | Filter by dataset (query parameter)          |
| `dataset_item_uid` | string (UUID) | No       | Filter by dataset item (query parameter)     |
| `cursor`           | string        | No       | Cursor for pagination (query parameter)      |
| `limit`            | integer       | No       | Number of results per page (query parameter) |

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.avala.ai/api/v1/models/runs/?run_status=completed" \
    -H "X-Avala-Api-Key: $AVALA_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.avala.ai/api/v1/models/runs/",
      headers={"X-Avala-Api-Key": "YOUR_API_KEY"},
      params={"run_status": "completed"}
  )
  runs = response.json()["results"]
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api.avala.ai/api/v1/models/runs/?run_status=completed",
    {
      headers: { "X-Avala-Api-Key": "YOUR_API_KEY" },
    }
  );
  const { results } = await response.json();
  ```

  ```go Go theme={null}
  req, _ := http.NewRequest("GET", "https://api.avala.ai/api/v1/models/runs/?run_status=completed", nil)
  req.Header.Set("X-Avala-Api-Key", "YOUR_API_KEY")

  resp, err := http.DefaultClient.Do(req)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "next": null,
  "previous": null,
  "results": [
    {
      "uid": "a4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d",
      "run_status": "completed",
      "type": "partial",
      "integration_uid": "e2f3a4b5-c6d7-8e9f-0a1b-2c3d4e5f6a7b",
      "dataset": [
        {
          "dataset_uid": "550e8400-e29b-41d4-a716-446655440000",
          "dataset_item_uids": [
            "660f9500-f30c-52e5-b827-557766551111",
            "771a0600-a41d-63f6-c938-668877662222"
          ]
        }
      ],
      "created_at": "2025-03-15T10:00:00Z",
      "updated_at": "2025-03-15T10:05:00Z"
    }
  ]
}
```

### Run Fields

| Field             | Type              | Description                                                         |
| ----------------- | ----------------- | ------------------------------------------------------------------- |
| `uid`             | string (UUID)     | Unique identifier for the run                                       |
| `run_status`      | string            | Run status: `pending`, `running`, `completed`, or `failed`          |
| `type`            | string            | Run type: `full` (entire dataset) or `partial` (specific items)     |
| `integration_uid` | string (UUID)     | UID of the integration used                                         |
| `dataset`         | array             | Array of dataset objects with `dataset_uid` and `dataset_item_uids` |
| `created_at`      | string (datetime) | ISO 8601 timestamp of creation                                      |
| `updated_at`      | string (datetime) | ISO 8601 timestamp of the last update                               |

***

## Get Run

```
GET /api/v1/models/runs/{uid}/
```

Returns the details of a specific prediction run.

### Parameters

| Name  | Type          | Required | Description              |
| ----- | ------------- | -------- | ------------------------ |
| `uid` | string (UUID) | Yes      | Run UID (path parameter) |

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.avala.ai/api/v1/models/runs/a4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d/" \
    -H "X-Avala-Api-Key: $AVALA_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.avala.ai/api/v1/models/runs/a4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d/",
      headers={"X-Avala-Api-Key": "YOUR_API_KEY"}
  )
  run = response.json()
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api.avala.ai/api/v1/models/runs/a4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d/",
    {
      headers: { "X-Avala-Api-Key": "YOUR_API_KEY" },
    }
  );
  const run = await response.json();
  ```

  ```go Go theme={null}
  req, _ := http.NewRequest("GET", "https://api.avala.ai/api/v1/models/runs/a4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d/", nil)
  req.Header.Set("X-Avala-Api-Key", "YOUR_API_KEY")

  resp, err := http.DefaultClient.Do(req)
  ```
</CodeGroup>

### Response

Same format as individual items in [List Runs](#list-runs).

***

## List Predictions

```
GET /api/v1/models/runs/{uid}/predictions/
```

Returns prediction results for a specific run, grouped by dataset and dataset item.

### Parameters

| Name               | Type          | Required | Description                              |
| ------------------ | ------------- | -------- | ---------------------------------------- |
| `uid`              | string (UUID) | Yes      | Run UID (path parameter)                 |
| `dataset_uid`      | string (UUID) | No       | Filter by dataset (query parameter)      |
| `dataset_item_uid` | string (UUID) | No       | Filter by dataset item (query parameter) |

### Request

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.avala.ai/api/v1/models/runs/a4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d/predictions/" \
    -H "X-Avala-Api-Key: $AVALA_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.avala.ai/api/v1/models/runs/a4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d/predictions/",
      headers={"X-Avala-Api-Key": "YOUR_API_KEY"}
  )
  predictions = response.json()
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    "https://api.avala.ai/api/v1/models/runs/a4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d/predictions/",
    {
      headers: { "X-Avala-Api-Key": "YOUR_API_KEY" },
    }
  );
  const predictions = await response.json();
  ```

  ```go Go theme={null}
  req, _ := http.NewRequest("GET", "https://api.avala.ai/api/v1/models/runs/a4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d/predictions/", nil)
  req.Header.Set("X-Avala-Api-Key", "YOUR_API_KEY")

  resp, err := http.DefaultClient.Do(req)
  ```
</CodeGroup>

### Response

```json theme={null}
[
  {
    "dataset_uid": "550e8400-e29b-41d4-a716-446655440000",
    "dataset_item_uid": "660f9500-f30c-52e5-b827-557766551111",
    "predictions": {
      "nodes": [
        {
          "uid": "b5c6d7e8-f9a0-1b2c-3d4e-5f6a7b8c9d0e",
          "annotation": {
            "task_name": "segmentation",
            "object": "car",
            "data": {
              "mask": "base64-encoded-mask-data",
              "confidence": 0.95
            }
          },
          "project_index": 0,
          "status": "accepted",
          "annotator": null,
          "reviewer": null,
          "children": []
        }
      ]
    }
  }
]
```

### Prediction Fields

| Field              | Type          | Description                                                  |
| ------------------ | ------------- | ------------------------------------------------------------ |
| `dataset_uid`      | string (UUID) | Dataset the prediction belongs to                            |
| `dataset_item_uid` | string (UUID) | Dataset item the prediction was generated for                |
| `predictions`      | object        | Prediction results containing an array of annotation `nodes` |

Each node in `predictions.nodes` contains:

| Field           | Type           | Description                                                 |
| --------------- | -------------- | ----------------------------------------------------------- |
| `uid`           | string (UUID)  | Unique identifier for the prediction                        |
| `annotation`    | object         | Annotation data including `task_name`, `object`, and `data` |
| `project_index` | integer        | Project index (typically `0`)                               |
| `status`        | string         | Prediction status                                           |
| `annotator`     | object \| null | Annotator info (always `null` for model predictions)        |
| `reviewer`      | object \| null | Reviewer info (always `null` for model predictions)         |
| `children`      | array          | Child prediction nodes (for hierarchical annotations)       |

***

## Run Statuses

| Status      | Description                         |
| ----------- | ----------------------------------- |
| `pending`   | Run is queued for processing        |
| `running`   | Predictions are being generated     |
| `completed` | All predictions have been generated |
| `failed`    | Run failed during processing        |

***

## Error Responses

### Validation Error (400)

```json theme={null}
{
  "dataset_uid": ["Invalid dataset UID."],
  "dataset_item_uids": ["Invalid dataset item UIDs"]
}
```

Returned when the request body contains invalid UIDs or the dataset items do not belong to the specified dataset.

### Unauthorized (401)

```json theme={null}
{
  "detail": "Invalid API key."
}
```

Returned when the `X-Avala-Api-Key` header is missing or contains an invalid key.

### Permission Denied (403)

```json theme={null}
{
  "detail": "You do not have permission to perform this action."
}
```

Returned when the authenticated user does not have access to the requested model or integration.

### Not Found (404)

```json theme={null}
{
  "detail": "Not found."
}
```

Returned when the specified model, integration, or run UID does not exist.