Skip to content
Lumean API
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.

orders.read

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

Required key permission: orders.read.

On this page(4)

Parameters

The inputs live inside the request line: fill in a value and you get a ready URL. Below are the type, whether it is required and the allowed values of every parameter.

GEThttps://api.lumean.app/api/public/orders//items
  • stringin pathrequired

    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.

    The value goes straight into the request line above.

Possible responses

200

Success. The payload is in data.

Body example
{
  "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"
    }
  ]
}
Response fields
successrequired

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.

boolean
messagerequired

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.

string
datarequired

Every fragment of the order, retries and regenerations included. Assembly order comes from chunk_index, not from the position in the list.

array<OrderItem>OrderItem
array item
idrequired

Chunk UUID. Use it in /orders/{order}/items/{item}/… paths.

string
order_idrequired

UUID of the order this chunk belongs to.

string
item_typerequired

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.

string
chunk_indexrequired

Zero-based position of the fragment within the order. It defines the order in which the final file is assembled.

nullable
integer
paragraph_indexrequired

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.

string
parent_item_idrequired

UUID of the source chunk — present on retry and regeneration records. null on an original chunk.

string
original_text_lengthrequired

Length of the text the fragment was created with. It is the ceiling for text in regenerate.

integer
current_text_lengthrequired

Length of the fragment’s current text: after a regeneration it differs from original_text_length.

integer
price_unitsrequired

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).

integer
consumed_unitsrequired

How many tokens were actually charged for this fragment. Zero while the fragment is unfinished.

integer
remaining_lockedrequired

How many tokens are still reserved for the fragment. Drops to zero once the fragment finishes or is cancelled.

integer
statusrequired

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.

string
result_filerequired

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.

nullable
object | string | null
duration_msrequired

Duration of the produced audio in milliseconds — the length of the recording, not the generation time. null for non-audio tasks.

nullable
integer
attempt_numberrequired

Attempt number for this fragment, starting at 1. It grows with every retry.

integer
can_retryrequired

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.

boolean
can_regeneraterequired

Whether a paid regeneration is allowed right now. Available for finished fragments only.

boolean
created_atrequired

When the fragment was created, ISO 8601.

nullabledate-time
string
updated_atrequired

When the fragment last changed, ISO 8601.

nullabledate-time
string
failure_reasonoptional

Machine-readable failure reason — present only on failed and policy_flagged. Everything else gets null.

nullable
string
401

The key is missing, unknown, disabled or expired.

Analyse this response
Body example
{
  "success": false,
  "message": "API key is missing. Provide it in the X-API-KEY header.",
  "data": null
}
Response fields
successrequired

Always false in error responses.

boolean
messagerequired

Error text in the key's language (set through the X-Locale header).

string
datarequired

Always null when the request is rejected before processing.

nullable
null
403

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

Analyse this response
Body example
{
  "success": false,
  "message": "This API key does not have permission to perform this action."
}
Response fields
messagerequired

Error overview.

string
404

Not found, or not reachable with this key.

Analyse this response
Body example
{
  "success": false,
  "message": "Resource not found."
}
Response fields
messagerequired

Error overview.

string

Events this produces

Progress arrives over WebSocket: polling the order in a loop is not required. Subscribing needs the same scope as reading orders.

Nearby

Objects

Feed this page to an AI

Open .mdllm.md

spec 0.0.1