Orders

Track content generation orders, poll their status, and read per-job outcomes including output URLs and failure categories.

Every generation request you submit creates an order. An order groups one or more jobs — one per asset being generated. These endpoints let you follow that work to completion.

Both require the content.read scope.

GET /api/external/orders

List recent orders for your account, newest first. No job breakdown — use the detail endpoint for that.

Query parameters

Parameter	Type	Description
`status`	string	Filter by order status.
`limit`	number	How many to return. Clamped to `[1, 50]`, default `20`.
`since`	string	ISO 8601 timestamp; only orders created after it.

Response

{
  "orders": [
    {
      "orderId": "131a2aec-...",
      "status": "in_progress",
      "jobType": "video",
      "provider": "pollo",
      "model": "mixed",
      "jobsTotal": 2,
      "jobsCompleted": 1,
      "jobsFailed": 0,
      "createdAt": "2026-05-06T07:42:52.668Z",
      "updatedAt": "2026-05-06T07:43:18.016Z"
    }
  ],
  "limit": 20,
  "returned": 1
}

GET /api/external/orders/:id

One order with its full per-job breakdown.

Path parameters

Parameter	Type	Description
`id`	string	The order UUID returned when you created it.

Response

{
  "orderId": "131a2aec-...",
  "status": "completed",
  "jobType": "video",
  "provider": "pollo",
  "model": "mixed",
  "jobsTotal": 2,
  "jobsCompleted": 2,
  "jobsFailed": 0,
  "createdAt": "...",
  "updatedAt": "...",
  "jobs": [
    {
      "jobId": "...",
      "provider": "pollo",
      "model": "kling-2.6",
      "status": "completed",
      "attemptCount": 2,
      "outputUrl": "https://storage.../video.mp4",
      "errorCategory": null,
      "errorHint": null,
      "startedAt": "...",
      "completedAt": "..."
    }
  ]
}

Job fields

Field	Description
`status`	`pending`, `in_progress`, `completed`, `failed`, `retry_pending`, `cancelled`, `expired`.
`attemptCount`	How many times the job has run. Greater than 1 means it was retried.
`outputUrl`	The generated asset. Populated only for `completed` jobs, otherwise `null`.
`errorCategory`	Why the job failed — see Job Failure Categories. `null` unless it failed.
`errorHint`	One sentence explaining the category. Display it; do not parse it.

Polling

Orders complete asynchronously. Poll the detail endpoint until status is completed, failed, or cancelled.

Two things worth knowing before you build the loop:

A failed job is not always final. TRANSIENT_INFRA, RATE_LIMIT, and PROVIDER_CAPACITY are retried automatically, so a job can report one of them and still finish successfully on a later attempt. Watch status and attemptCount, not the presence of an errorCategory.

Partial completion is normal. An order with several jobs can end with some completed and some failed. Read jobsCompleted and jobsFailed rather than assuming the order is all-or-nothing.

Respect the rate limit of 60 requests per minute — see Rate Limiting. Polling every few seconds per order is ample; generation takes far longer than that.

Errors

Code	Cause
`400`	`id` is not a valid UUID, or a query parameter is invalid.
`401`	Missing, invalid, or revoked API key.
`403`	The key lacks the `content.read` scope.
`404`	The order does not exist, or belongs to another account. These are deliberately indistinguishable.
`429`	Rate limit exceeded.