Models - Avala Documentation

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

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.

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

curl "https://api.avala.ai/api/v1/models/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

import requests

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

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

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)

Response

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

curl "https://api.avala.ai/api/v1/models/d1e2f3a4-b5c6-7d8e-9f0a-1b2c3d4e5f6a/integrations/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

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"]

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();

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)

Response

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

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"
      ]
    }
  ]'

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()

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();

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)

Response

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

curl "https://api.avala.ai/api/v1/models/runs/?run_status=completed" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

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"]

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();

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)

Response

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

curl "https://api.avala.ai/api/v1/models/runs/a4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

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()

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();

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)

Response

Same format as individual items in 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

curl "https://api.avala.ai/api/v1/models/runs/a4b5c6d7-e8f9-0a1b-2c3d-4e5f6a7b8c9d/predictions/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

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()

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();

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)

Response

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

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

{
  "detail": "Invalid API key."
}

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

Permission Denied (403)

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

{
  "detail": "Not found."
}

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

​List Models

​Parameters

​Request

​Response

​Fields

​List Integrations

​Parameters

​Request

​Response

​Integration Fields

​Create Prediction Run

​Parameters

​Request

​Response

​List Runs

​Parameters

​Request

​Response

​Run Fields

​Get Run

​Parameters

​Request

​Response

​List Predictions

​Parameters

​Request

​Response

​Prediction Fields

​Run Statuses

​Error Responses

​Validation Error (400)

​Unauthorized (401)

​Permission Denied (403)

​Not Found (404)

List Models

Parameters

Request

Response

Fields

List Integrations

Parameters

Request

Response

Integration Fields

Create Prediction Run

Parameters

Request

Response

List Runs

Parameters

Request

Response

Run Fields

Get Run

Parameters

Request

Response

List Predictions

Parameters

Request

Response

Prediction Fields

Run Statuses

Error Responses

Validation Error (400)

Unauthorized (401)

Permission Denied (403)

Not Found (404)