> ## Documentation Index
> Fetch the complete documentation index at: https://avala.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Dataset Items

> API reference for dataset items and sequences

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

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.avala.ai/api/v1/datasets/johndoe/training-images/items/" \
    -H "X-Avala-Api-Key: $AVALA_API_KEY"
  ```

  ```python Python theme={null}
  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"]
  ```

  ```typescript TypeScript theme={null}
  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();
  ```

  ```go Go theme={null}
  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)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  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"
  ```

  ```python Python theme={null}
  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()
  ```

  ```typescript TypeScript theme={null}
  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();
  ```

  ```go Go theme={null}
  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)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.avala.ai/api/v1/datasets/johndoe/lidar-captures/sequences/" \
    -H "X-Avala-Api-Key: $AVALA_API_KEY"
  ```

  ```python Python theme={null}
  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"]
  ```

  ```typescript TypeScript theme={null}
  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();
  ```

  ```go Go theme={null}
  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)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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)

```json theme={null}
{
  "detail": "Not found."
}
```

Returned when the specified owner, dataset, or item does not exist.

### Permission Denied (403)

```json theme={null}
{
  "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)

```json theme={null}
{
  "detail": "Invalid API key."
}
```

Returned when the `X-Avala-Api-Key` header is missing or contains an invalid key.