Skip to main content
List and retrieve datasets and their sequences.

​
List Datasets

GET /api/v1/datasets/{owner_name}/list/
Returns all datasets belonging to a specific owner that are visible to the authenticated user.

​
Parameters

NameTypeRequiredDescription
owner_namestringYesUsername of the dataset owner (path parameter)
orderingstringNoField to order results by (query parameter)
pageintegerNoPage number for pagination (query parameter)
limitintegerNoNumber of results per page (query parameter)

​
Request

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

​
Response

{
  "count": 25,
  "next": "https://server.avala.ai/api/v1/datasets/johndoe/list/?page=2",
  "previous": null,
  "results": [
    {
      "uid": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Training Images",
      "slug": "training-images",
      "data_type": "image",
      "is_sequence": false,
      "visibility": "private",
      "status": "created",
      "item_count": 1000,
      "project_count": 2,
      "owner_name": "johndoe",
      "size_bytes": 5368709120,
      "annotations_count": 4500
    }
  ]
}

​
Fields

FieldTypeDescription
uidstring (UUID)Unique identifier for the dataset
namestringDisplay name of the dataset
slugstringURL-friendly identifier
data_typestringType of data in the dataset (image, lidar, video, or mcap)
is_sequencebooleanWhether the dataset contains sequences
visibilitystringpublic or private
statusstringCurrent dataset status (creating or created)
item_countintegerNumber of items in the dataset
project_countintegerNumber of projects associated with the dataset
owner_namestringUsername of the dataset owner
size_bytesintegerTotal size of the dataset in bytes
annotations_countintegerTotal number of annotations across all items

​
List Sequences

GET /api/v1/datasets/{owner_name}/{dataset_slug}/sequences/
Returns sequences within a dataset. Used for video and LiDAR datasets that contain frame sequences.

​
Parameters

NameTypeRequiredDescription
owner_namestringYesUsername of the dataset owner (path parameter)
dataset_slugstringYesSlug identifier of the dataset (path parameter)
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/datasets/johndoe/lidar-captures/sequences/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

​
Response

{
  "next": null,
  "previous": null,
  "results": [
    {
      "uid": "660f9500-f39c-52e5-b827-557766550000",
      "key": "sequence_001",
      "status": "completed",
      "featured_image": "https://storage.avala.ai/sequences/seq_001/featured.jpg",
      "number_of_frames": 150,
      "views": [
        {
          "key": "camera_front",
          "load": "https://storage.avala.ai/sequences/seq_001/camera_front/",
          "metrics": null
        }
      ]
    }
  ]
}

​
Fields

FieldTypeDescription
uidstring (UUID)Unique identifier for the sequence
keystringSequence key name
statusstringCurrent workflow status of the sequence
featured_imagestringURL to the featured preview image
number_of_framesintegerTotal number of frames in the sequence
viewsarrayArray of view objects, each containing key, load, and metrics

​
Data Types

TypeDescription
imageSingle images (JPEG, PNG, WebP)
videoVideo files converted to frame sequences
lidarPoint cloud data (PCD, PLY)
mcapMCAP files with sensor data

​
Dataset Status

StatusDescription
creatingDataset is being created and is not yet ready
createdDataset has been created and is ready for use

​
Sequence Status Values

Sequences progress through various workflow statuses during the annotation lifecycle.
StatusDescription
unattemptedNot yet started
pendingAwaiting processing
completedFully annotated and reviewed
rework_requiredNeeds corrections
ready_for_annotationReady to be annotated
labeling_4d3D/4D annotation in progress
review_4d3D/4D annotation review in progress
ready_for_2dReady for 2D annotation
labeling_2d2D annotation in progress
review_2d2D annotation review in progress
final_reviewFinal quality control review
customer_approvedApproved by the customer

​
Error Responses

​
Not Found (404)

{
  "detail": "Not found."
}
Returned when the specified owner or dataset does not exist.

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

​
Unauthorized (401)

{
  "detail": "Invalid API key."
}
Returned when the X-Avala-Api-Key header is missing or contains an invalid key.