Skip to main content
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

NameTypeRequiredDescription
cursorstringNoCursor for pagination (query parameter)
limitintegerNoNumber of results per page (query parameter)

​
Request

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

​
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

FieldTypeDescription
uidstring (UUID)Unique identifier for the model
namestringDisplay name of the model
descriptionstringHuman-readable description of the model
model_type_namestringName of the model type (e.g., segmentation, detection)
model_type_descriptionstringDescription of the model type
is_publicbooleanWhether this model is publicly available
created_atstring (datetime)ISO 8601 timestamp of creation
updated_atstring (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

NameTypeRequiredDescription
model_uidstring (UUID)YesModel UID (path parameter)
cursorstringNoCursor for pagination (query parameter)
limitintegerNoNumber 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"

​
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

FieldTypeDescription
uidstring (UUID)Unique identifier for the integration
provider_namestringName of the provider (e.g., AWS SageMaker)
provider_config_typestringType of the provider config (e.g., real-time, batch)
provider_config_uidstring (UUID)UID of the underlying provider configuration
provider_config_namestringDisplay name of the provider configuration
created_atstring (datetime)ISO 8601 timestamp of creation
updated_atstring (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

NameTypeRequiredDescription
integration_uidstring (UUID)YesIntegration UID (path parameter)
The request body is an array of objects, each specifying a dataset and optionally specific items:
NameTypeRequiredDescription
dataset_uidstring (UUID)YesDataset to run predictions on
dataset_item_uidsarrayYesItem 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"
      ]
    }
  ]'

​
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

NameTypeRequiredDescription
integration_uidstring (UUID)NoFilter by integration (query parameter)
run_statusstringNoFilter by status (query parameter)
dataset_uidstring (UUID)NoFilter by dataset (query parameter)
dataset_item_uidstring (UUID)NoFilter by dataset item (query parameter)
cursorstringNoCursor for pagination (query parameter)
limitintegerNoNumber 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"

​
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

FieldTypeDescription
uidstring (UUID)Unique identifier for the run
run_statusstringRun status: pending, running, completed, or failed
typestringRun type: full (entire dataset) or partial (specific items)
integration_uidstring (UUID)UID of the integration used
datasetarrayArray of dataset objects with dataset_uid and dataset_item_uids
created_atstring (datetime)ISO 8601 timestamp of creation
updated_atstring (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

NameTypeRequiredDescription
uidstring (UUID)YesRun 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"

​
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

NameTypeRequiredDescription
uidstring (UUID)YesRun UID (path parameter)
dataset_uidstring (UUID)NoFilter by dataset (query parameter)
dataset_item_uidstring (UUID)NoFilter 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"

​
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

FieldTypeDescription
dataset_uidstring (UUID)Dataset the prediction belongs to
dataset_item_uidstring (UUID)Dataset item the prediction was generated for
predictionsobjectPrediction results containing an array of annotation nodes
Each node in predictions.nodes contains:
FieldTypeDescription
uidstring (UUID)Unique identifier for the prediction
annotationobjectAnnotation data including task_name, object, and data
project_indexintegerProject index (typically 0)
statusstringPrediction status
annotatorobject | nullAnnotator info (always null for model predictions)
reviewerobject | nullReviewer info (always null for model predictions)
childrenarrayChild prediction nodes (for hierarchical annotations)

​
Run Statuses

StatusDescription
pendingRun is queued for processing
runningPredictions are being generated
completedAll predictions have been generated
failedRun 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.