Skip to main content
List and retrieve individual items and sequences within datasets.

​
List Items

GET /api/v1/datasets/{owner_name}/{dataset_slug}/items/
Returns all items in a dataset, ordered by most recent first. Items represent individual data files (images, point clouds, etc.) within a dataset.

​
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/training-images/items/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

​
Response

{
  "next": "https://server.avala.ai/api/v1/datasets/johndoe/training-images/items/?cursor=cD0yMDI1",
  "previous": null,
  "results": [
    {
      "uid": "550e8400-e29b-41d4-a716-446655440000",
      "key": "image_001.jpg",
      "status": "completed",
      "data_url": "https://storage.avala.ai/datasets/training-images/image_001.jpg",
      "thumbnail_url": "https://storage.avala.ai/datasets/training-images/thumbnails/image_001.jpg",
      "metadata": {
        "width": 1920,
        "height": 1080,
        "format": "jpeg"
      },
      "annotations_count": 12,
      "created_at": "2025-01-15T09:30:00Z"
    }
  ]
}

​
Fields

FieldTypeDescription
uidstring (UUID)Unique identifier for the item
keystringItem key name (typically the filename)
statusstringCurrent workflow status of the item
data_urlstringURL to the full-resolution data file
thumbnail_urlstringURL to the thumbnail preview image
metadataobjectItem metadata including dimensions and format
annotations_countintegerNumber of annotations on this item
created_atstring (datetime)ISO 8601 timestamp of when the item was created

​
Get Item

GET /api/v1/datasets/{owner_name}/{dataset_slug}/items/{item_uid}/
Returns a specific item by its unique identifier, including full metadata and annotation count.

​
Parameters

NameTypeRequiredDescription
owner_namestringYesUsername of the dataset owner (path parameter)
dataset_slugstringYesSlug identifier of the dataset (path parameter)
item_uidstring (UUID)YesUnique identifier of the item (path parameter)

​
Request

curl "https://server.avala.ai/api/v1/datasets/johndoe/training-images/items/550e8400-e29b-41d4-a716-446655440000/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

​
Response

{
  "uid": "550e8400-e29b-41d4-a716-446655440000",
  "key": "image_001.jpg",
  "status": "completed",
  "data_url": "https://storage.avala.ai/datasets/training-images/image_001.jpg",
  "thumbnail_url": "https://storage.avala.ai/datasets/training-images/thumbnails/image_001.jpg",
  "metadata": {
    "width": 1920,
    "height": 1080,
    "format": "jpeg"
  },
  "annotations_count": 12,
  "created_at": "2025-01-15T09:30:00Z"
}

​
Fields

FieldTypeDescription
uidstring (UUID)Unique identifier for the item
keystringItem key name (typically the filename)
statusstringCurrent workflow status of the item
data_urlstringURL to the full-resolution data file
thumbnail_urlstringURL to the thumbnail preview image
metadataobjectItem metadata including dimensions and format
annotations_countintegerNumber of annotations on this item
created_atstring (datetime)ISO 8601 timestamp of when the item was created

​
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

​
Item Status Values

Items progress through various workflow statuses during the annotation lifecycle.
StatusDescription
unattemptedNot yet started
pendingAwaiting processing
ready_for_annotationReady to be annotated
in_progressAnnotation is currently in progress
completedFully annotated and reviewed
rework_requiredNeeds corrections
customer_approvedApproved by the customer

​
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, dataset, or item 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 or item.

​
Unauthorized (401)

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