---
title: "GET /orders/{order}/items — List Order Items"
url: https://lumean.app/en/developers/docs/api/get-orders-order-items
locale: en
description: "List Order Items"
generated: 2026-10-17
operationId: orderItem.index
method: GET
path: "/orders/{order}/items"
scopes: [orders.read]
spec_version: 0.0.1
---

# GET /orders/{order}/items

**List Order Items**

Returns the order's chunks. Long text is split into chunks, each generated
independently — this is where you see which ones succeeded and which did not.

Chunk statuses: `pending`, `processing`, `completed`, `policy_flagged` (rejected by
the provider's content policy), `failed` (technical error).

**Required key permission:** `orders.read`.

- Required scope: `orders.read`

## Request

```bash
curl -X GET 'https://api.lumean.app/api/public/orders/{order}/items' \
  -H 'Accept: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY'
```

## Parameters

| Field | In | Type | Req. | Description |
| --- | --- | --- | --- | --- |
| `order` | path | `string` | required | Order UUID — 36 characters shaped like `9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c`, not a number. Take it from the `id` field: `POST /orders` returns it on creation and `GET /orders` lists it. Someone else’s order will not open with your key — you get a `404`. default: `9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c` |

## Request body

No body.

## Responses

### 200 — Success. The payload is in `data`.

**Response fields**

| Field | Type | Req. | Description |
| --- | --- | --- | --- |
| `success` | `boolean` | required | Success flag. Branch on the HTTP status code instead: any 2xx response carries `true` here, while an error comes back in a different shape that need not contain this field at all. |
| `message` | `string` | required | A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code. |
| `data` | `array<OrderItem>` | required | Every fragment of the order, retries and regenerations included. Assembly order comes from `chunk_index`, not from the position in the list. |
| `data[].id` | `string` | required | Chunk UUID. Use it in `/orders/{order}/items/{item}/…` paths. |
| `data[].order_id` | `string` | required | UUID of the order this chunk belongs to. |
| `data[].item_type` | `string` | required | What the record is: `chunk` is an original fragment, `retry` a free re-run of a failed one, `regeneration` a paid redo of a finished one. Retries and regenerations are separate records sharing the same `chunk_index`: the full attempt history is kept, and the last one is what the result plays. |
| `data[].chunk_index` | `integer` — nullable | required | Zero-based position of the fragment within the order. It defines the order in which the final file is assembled. |
| `data[].paragraph_index` | `string` | required | The paragraph this fragment belongs to — filled in only for the original fragments of a paragraph-mode order. It is `null` both in ordinary mode and on retry or regeneration records: those carry no paragraph link of their own and inherit it from the parent fragment via `parent_item_id`. The mode is switched on by the `generation_mode` key in the order's `config_override`. |
| `data[].parent_item_id` | `string` | required | UUID of the source chunk — present on `retry` and `regeneration` records. `null` on an original chunk. |
| `data[].original_text_length` | `integer` | required | Length of the text the fragment was created with. It is the ceiling for `text` in `regenerate`. |
| `data[].current_text_length` | `integer` | required | Length of the fragment’s current text: after a regeneration it differs from `original_text_length`. |
| `data[].price_units` | `integer` | required | Cost of the fragment in **tokens** — not money. The monetary amount lives on the order itself, in its own `price_units` field (LMC there, tokens here; the names match, the units do not). |
| `data[].consumed_units` | `integer` | required | How many tokens were actually charged for this fragment. Zero while the fragment is unfinished. |
| `data[].remaining_locked` | `integer` | required | How many tokens are still reserved for the fragment. Drops to zero once the fragment finishes or is cancelled. |
| `data[].status` | `string` | required | Fragment state: `pending` waits for a worker, `processing` is in flight, `completed` is done, `failed` hit a technical error, and `policy_flagged` was rejected by the content policy. The difference between the last two dictates the fix: `failed` is cured by retrying as is, whereas `policy_flagged` requires rewording — retrying the same text is rejected again. |
| `data[].result_file` | `object \| string \| null` — nullable | required | The finished fragment’s file: an absolute path, or a structure carrying path and size. Download it via `POST /storage/url`, same as order files. `null` until the fragment is ready. |
| `data[].duration_ms` | `integer` — nullable | required | Duration of the produced audio in milliseconds — the length of the recording, not the generation time. `null` for non-audio tasks. |
| `data[].attempt_number` | `integer` | required | Attempt number for this fragment, starting at 1. It grows with every retry. |
| `data[].can_retry` | `boolean` | required | Whether a free retry is allowed right now. It already accounts for status, task type and exhausted attempts, so you need not re-check the conditions. |
| `data[].can_regenerate` | `boolean` | required | Whether a paid regeneration is allowed right now. Available for finished fragments only. |
| `data[].created_at` | `string` — date-time — nullable | required | When the fragment was created, ISO 8601. |
| `data[].updated_at` | `string` — date-time — nullable | required | When the fragment last changed, ISO 8601. |
| `data[].failure_reason` | `string` — nullable | — | Machine-readable failure reason — present only on `failed` and `policy_flagged`. Everything else gets `null`. |

**Example**

```json
{
  "success": true,
  "message": "Order items retrieved successfully.",
  "data": [
    {
      "id": "d4e5f6a7-8b9c-4d0e-8f1a-2b3c4d5e6f7a",
      "order_id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c",
      "item_type": "chunk",
      "chunk_index": 0,
      "parent_item_id": null,
      "original_text_length": 240,
      "current_text_length": 240,
      "price_units": 240,
      "consumed_units": 240,
      "remaining_locked": 0,
      "status": "completed",
      "result_file": {
        "path": "storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/chunks/0/result.mp3",
        "storage": "s3",
        "name": "chunk_0.mp3",
        "size": 512340,
        "mime_type": "audio/mpeg",
        "size_formatted": "500.33 KB"
      },
      "attempt_number": 1,
      "can_retry": false,
      "can_regenerate": true,
      "created_at": "2026-07-17T12:00:05+00:00",
      "updated_at": "2026-07-17T12:02:10+00:00"
    },
    {
      "id": "e5f6a7b8-9c0d-4e1f-8a2b-3c4d5e6f7a8b",
      "order_id": "9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c",
      "item_type": "chunk",
      "chunk_index": 1,
      "parent_item_id": null,
      "original_text_length": 180,
      "current_text_length": 180,
      "price_units": 180,
      "consumed_units": 180,
      "remaining_locked": 0,
      "status": "completed",
      "result_file": {
        "path": "storage/501/orders/9f8b2c1a-4d3e-4f5a-8b9c-0d1e2f3a4b5c/output/chunks/1/result.mp3",
        "storage": "s3",
        "name": "chunk_1.mp3",
        "size": 398210,
        "mime_type": "audio/mpeg",
        "size_formatted": "388.88 KB"
      },
      "attempt_number": 1,
      "can_retry": false,
      "can_regenerate": true,
      "created_at": "2026-07-17T12:00:05+00:00",
      "updated_at": "2026-07-17T12:02:45+00:00"
    }
  ]
}
```

### 401 — The key is missing, unknown, disabled or expired.

**Response fields**

| Field | Type | Req. | Description |
| --- | --- | --- | --- |
| `success` | `boolean` | required | Always `false` in error responses. |
| `message` | `string` | required | Error text in the key's language (set through the `X-Locale` header). |
| `data` | `null` — nullable | required | Always `null` when the request is rejected before processing. |

**Example**

```json
{
  "success": false,
  "message": "API key is missing. Provide it in the X-API-KEY header.",
  "data": null
}
```

### 403 — The key lacks the required permission, or the object belongs to another user.

**Response fields**

| Field | Type | Req. | Description |
| --- | --- | --- | --- |
| `message` | `string` | required | Error overview. |

**Example**

```json
{
  "success": false,
  "message": "This API key does not have permission to perform this action."
}
```

### 404 — Not found, or not reachable with this key.

**Response fields**

| Field | Type | Req. | Description |
| --- | --- | --- | --- |
| `message` | `string` | required | Error overview. |

**Example**

```json
{
  "success": false,
  "message": "Resource not found."
}
```

---

- This page in the browser: https://lumean.app/en/developers/docs/api/get-orders-order-items
- Full machine-readable reference: https://api.lumean.app/docs/llm.md