Skip to main content
Export annotation results from datasets and projects.

​
List Exports

GET /api/v1/exports/
Returns all exports visible to the authenticated user, ordered by most recent first.

​
Parameters

NameTypeRequiredDescription
orderingstringNoField to order results by (query parameter)
cursorstringNoCursor for pagination (query parameter)
limitintegerNoNumber of results per page (query parameter)

​
Request

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

​
Response

{
  "next": null,
  "previous": null,
  "results": [
    {
      "uid": "880b0700-h51e-74g7-d049-779988770000",
      "name": "Training Data Export",
      "format": "avala-json-external",
      "status": "exported",
      "total_task_count": 1000,
      "exported_task_count": 1000,
      "download_url": "https://storage.avala.ai/exports/880b0700.zip",
      "datasets": ["550e8400-e29b-41d4-a716-446655440000"],
      "slices": [],
      "projects": ["770a9600-g40d-63f6-c938-668877660000"],
      "organization": null,
      "created_at": "2025-01-21T10:00:00Z"
    }
  ]
}

​
Fields

FieldTypeDescription
uidstring (UUID)Unique identifier for the export
namestringDisplay name of the export
formatstringExport format used
statusstringCurrent export status
total_task_countintegerTotal number of tasks to export
exported_task_countintegerNumber of tasks exported so far
download_urlstringURL to download the export file (available when status is exported)
datasetsarrayArray of dataset UUIDs included in the export
slicesarrayArray of slice UUIDs included in the export
projectsarrayArray of project UUIDs included in the export
organizationobjectAssociated organization, if any
created_atstring (datetime)ISO 8601 timestamp of when the export was created

​
Create Export

POST /api/v1/exports/
Creates a new export job. Exports are processed asynchronously — poll the List Exports endpoint to check status and retrieve the download URL when complete.

​
Parameters

NameTypeRequiredDescription
namestringYesExport name (1-255 characters)
formatstringYesExport format (see Supported Formats below)
datasetsarrayYesArray of dataset UUIDs to export
projectsarrayYesArray of project UUIDs to export
slicesarrayYesArray of slice UUIDs to export
filter_query_stringstringNoFilter query to narrow exported results

​
Request

curl -X POST "https://server.avala.ai/api/v1/exports/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Export",
    "format": "avala-json-external",
    "datasets": ["550e8400-e29b-41d4-a716-446655440000"],
    "projects": [],
    "slices": []
  }'

​
Response

{
  "uid": "880b0700-h51e-74g7-d049-779988770000",
  "name": "My Export",
  "format": "avala-json-external",
  "status": "requested",
  "total_task_count": null,
  "exported_task_count": null,
  "download_url": null,
  "datasets": ["550e8400-e29b-41d4-a716-446655440000"],
  "slices": [],
  "projects": [],
  "organization": null,
  "created_at": "2025-01-21T10:00:00Z"
}

​
Fields

FieldTypeDescription
uidstring (UUID)Unique identifier for the created export
namestringExport name as provided
formatstringExport format as provided
statusstringInitial status, always requested
total_task_countintegernull until processing begins
exported_task_countintegernull until processing begins
download_urlstringnull until export completes
datasetsarrayDataset UUIDs included
slicesarraySlice UUIDs included
projectsarrayProject UUIDs included
organizationobjectAssociated organization
created_atstring (datetime)ISO 8601 timestamp of creation

​
Supported Formats

FormatDescription
avala-json-externalAvala’s native JSON format with full metadata and annotation details
YOLOYOLO format for object detection models

​
Avala Grouped JSON Schema

The avala-json-external format exports all annotation data in a single structured JSON file. The top-level structure groups data by datasets, projects, and results.

​
Top-Level Fields

FieldTypeDescription
scheme_versionstringSchema version number (e.g., "1.0")
export_infoobjectExport metadata including name, creation timestamp, and export parameters
datasetsarrayArray of dataset objects with their items
projectsarrayArray of project objects with their configurations and label taxonomies
resultsarrayArray of annotation result objects containing the actual annotations

​
Sample Structure

{
  "scheme_version": "1.0",
  "export_info": {
    "name": "Training Data Export",
    "created_at": "2025-01-21T10:00:00Z",
    "format": "avala-json-external",
    "filter_query_string": null
  },
  "datasets": [
    {
      "uid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Highway Scenes",
      "items": [
        {
          "uid": "660f9500-f30c-52e5-b827-557766551111",
          "ref_id": "frame_001",
          "metadata": { "weather": "clear", "time": "day" }
        }
      ]
    }
  ],
  "projects": [
    {
      "uid": "770a9600-g40d-63f6-c938-668877660000",
      "name": "Object Detection",
      "labels": [
        { "name": "car", "color": "#FF0000" },
        { "name": "pedestrian", "color": "#00FF00" }
      ]
    }
  ],
  "results": [
    {
      "uid": "880b0700-h51e-74g7-d049-779988770000",
      "dataset_item_uid": "660f9500-f30c-52e5-b827-557766551111",
      "project_uid": "770a9600-g40d-63f6-c938-668877660000",
      "annotations": [
        {
          "label": "car",
          "type": "bounding_box",
          "coordinates": { "x": 100, "y": 200, "width": 150, "height": 80 },
          "attributes": { "occluded": false, "truncated": false }
        }
      ]
    }
  ]
}

​
Export Statuses

StatusDescription
requestedExport has been requested and is queued for processing
exportingExport is actively being processed
exportedExport completed successfully and download_url is available
failedExport failed during processing
abortedExport was aborted before completion

​
Polling for Completion

Exports are processed asynchronously. After creating an export, poll the List Exports endpoint to check whether it has completed and retrieve the download URL.
We recommend a polling interval of 5 seconds. The download_url field will be populated once the export status transitions to exported.
import time
import requests

def wait_for_export(export_uid, api_key):
    headers = {"X-Avala-Api-Key": api_key}

    while True:
        response = requests.get(
            "https://server.avala.ai/api/v1/exports/",
            headers=headers
        )
        exports = response.json()["results"]

        export = next(
            (e for e in exports if e["uid"] == export_uid),
            None
        )

        if export and export["status"] == "exported":
            return export["download_url"]
        elif export and export["status"] == "failed":
            raise Exception("Export failed")

        time.sleep(5)

​
Error Responses

​
Validation Error (400)

{
  "name": ["This field is required."],
  "format": ["\"invalid\" is not a valid choice."]
}
Returned when the request body is missing required fields or contains invalid values.

​
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 resources.

​
Not Found (404)

{
  "detail": "Not found."
}
Returned when a referenced dataset, project, or slice UUID does not exist.