Dataset Items - Avala Documentation

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

Name	Type	Required	Description
`owner_name`	string	Yes	Username of the dataset owner (path parameter)
`dataset_slug`	string	Yes	Slug identifier of the dataset (path parameter)
`ordering`	string	No	Field to order results by (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/datasets/johndoe/training-images/items/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

import requests

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

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

req, _ := http.NewRequest("GET", "https://api.avala.ai/api/v1/datasets/johndoe/training-images/items/", nil)
req.Header.Set("X-Avala-Api-Key", "YOUR_API_KEY")

resp, err := http.DefaultClient.Do(req)

Response

{
  "next": "https://api.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

Field	Type	Description
`uid`	string (UUID)	Unique identifier for the item
`key`	string	Item key name (typically the filename)
`status`	string	Current workflow status of the item
`data_url`	string	URL to the full-resolution data file
`thumbnail_url`	string	URL to the thumbnail preview image
`metadata`	object	Item metadata including dimensions and format
`annotations_count`	integer	Number of annotations on this item
`created_at`	string (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

Name	Type	Required	Description
`owner_name`	string	Yes	Username of the dataset owner (path parameter)
`dataset_slug`	string	Yes	Slug identifier of the dataset (path parameter)
`item_uid`	string (UUID)	Yes	Unique identifier of the item (path parameter)

Request

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

import requests

response = requests.get(
    "https://api.avala.ai/api/v1/datasets/johndoe/training-images/items/550e8400-e29b-41d4-a716-446655440000/",
    headers={"X-Avala-Api-Key": "YOUR_API_KEY"}
)
item = response.json()

const response = await fetch(
  "https://api.avala.ai/api/v1/datasets/johndoe/training-images/items/550e8400-e29b-41d4-a716-446655440000/",
  {
    headers: { "X-Avala-Api-Key": "YOUR_API_KEY" },
  }
);
const item = await response.json();

req, _ := http.NewRequest("GET", "https://api.avala.ai/api/v1/datasets/johndoe/training-images/items/550e8400-e29b-41d4-a716-446655440000/", nil)
req.Header.Set("X-Avala-Api-Key", "YOUR_API_KEY")

resp, err := http.DefaultClient.Do(req)

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

Field	Type	Description
`uid`	string (UUID)	Unique identifier for the item
`key`	string	Item key name (typically the filename)
`status`	string	Current workflow status of the item
`data_url`	string	URL to the full-resolution data file
`thumbnail_url`	string	URL to the thumbnail preview image
`metadata`	object	Item metadata including dimensions and format
`annotations_count`	integer	Number of annotations on this item
`created_at`	string (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

Name	Type	Required	Description
`owner_name`	string	Yes	Username of the dataset owner (path parameter)
`dataset_slug`	string	Yes	Slug identifier of the dataset (path parameter)
`ordering`	string	No	Field to order results by (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/datasets/johndoe/lidar-captures/sequences/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

import requests

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

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

req, _ := http.NewRequest("GET", "https://api.avala.ai/api/v1/datasets/johndoe/lidar-captures/sequences/", nil)
req.Header.Set("X-Avala-Api-Key", "YOUR_API_KEY")

resp, err := http.DefaultClient.Do(req)

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

Field	Type	Description
`uid`	string (UUID)	Unique identifier for the sequence
`key`	string	Sequence key name
`status`	string	Current workflow status of the sequence
`featured_image`	string	URL to the featured preview image
`number_of_frames`	integer	Total number of frames in the sequence
`views`	array	Array of view objects, each containing `key`, `load`, and `metrics`

Item Status Values

Items progress through various workflow statuses during the annotation lifecycle.

Status	Description
`unattempted`	Not yet started
`pending`	Awaiting processing
`ready_for_annotation`	Ready to be annotated
`in_progress`	Annotation is currently in progress
`completed`	Fully annotated and reviewed
`rework_required`	Needs corrections
`customer_approved`	Approved by the customer

Sequence Status Values

Sequences progress through various workflow statuses during the annotation lifecycle.

Status	Description
`unattempted`	Not yet started
`pending`	Awaiting processing
`completed`	Fully annotated and reviewed
`rework_required`	Needs corrections
`ready_for_annotation`	Ready to be annotated
`labeling_4d`	3D/4D annotation in progress
`review_4d`	3D/4D annotation review in progress
`ready_for_2d`	Ready for 2D annotation
`labeling_2d`	2D annotation in progress
`review_2d`	2D annotation review in progress
`final_review`	Final quality control review
`customer_approved`	Approved 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.

​List Items

​Parameters

​Request

​Response

​Fields

​Get Item

​Parameters

​Request

​Response

​Fields

​List Sequences

​Parameters

​Request

​Response

​Fields

​Item Status Values

​Sequence Status Values

​Error Responses

​Not Found (404)

​Permission Denied (403)

​Unauthorized (401)

List Items

Parameters

Request

Response

Fields

Get Item

Parameters

Request

Response

Fields

List Sequences

Parameters

Request

Response

Fields

Item Status Values

Sequence Status Values

Error Responses

Not Found (404)

Permission Denied (403)

Unauthorized (401)