Datasets API
List and retrieve datasets and their items.
List Datasets
GET /api/v1/datasets/{owner_name}/list/Returns datasets belonging to an owner that are visible to the current user.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
owner_name | string | Username of the dataset owner |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
ordering | string | Field to order results by |
page | integer | Page number for pagination |
limit | integer | Results per page |
Example
cURL
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
}
]
}Dataset Fields
| Field | Type | Description |
|---|---|---|
uid | UUID | Unique identifier |
name | string | Dataset name |
slug | string | URL-friendly identifier |
data_type | string | image, lidar, video, or mcap |
is_sequence | boolean | Whether dataset contains sequences |
visibility | string | public or private |
status | string | creating or created |
item_count | integer | Number of items |
project_count | integer | Number of associated projects |
owner_name | string | Owner’s username |
size_bytes | integer | Total size in bytes |
annotations_count | integer | Total annotation count |
List Dataset Sequences
GET /api/v1/datasets/{owner_name}/{dataset_slug}/sequences/List sequences within a dataset. Used for video and LiDAR datasets with frame sequences.
Path Parameters
| Parameter | Type | Description |
|---|---|---|
owner_name | string | Username of the dataset owner |
dataset_slug | string | Dataset slug |
Query Parameters
| Parameter | Type | Description |
|---|---|---|
ordering | string | Field to order results by |
cursor | string | Pagination cursor |
limit | integer | Results per page |
Example
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": "seq-uuid-001",
"key": "sequence_001",
"status": "completed",
"featured_image": "https://...",
"number_of_frames": 150,
"views": [
{
"key": "camera_front",
"load": "https://...",
"metrics": null
}
]
}
]
}Sequence Status Values
Sequences can have various workflow statuses:
| 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 review in progress |
ready_for_2d | Ready for 2D annotation |
labeling_2d | 2D annotation in progress |
review_2d | 2D review in progress |
final_review | Final QC review |
customer_approved | Approved by customer |
Data Types
| Type | Description |
|---|---|
image | Single images (JPEG, PNG, WebP) |
video | Video files converted to frame sequences |
lidar | Point cloud data (PCD, PLY) |
mcap | MCAP files with sensor data |
Error Responses
Not Found
{
"detail": "Not found."
}HTTP Status: 404
Permission Denied
{
"detail": "You do not have permission to perform this action."
}HTTP Status: 403
Last updated on