Concepts · Generation Orders

Generation Orders

An order fans one workflow template out into N child runs with automated variation — the batch primitive behind catalog production. Every worker shift places its work as orders, so batches carry the same telemetry, budgets, and provenance as single runs.

Two-phase by design

lifecycleascii

POST /v1/orders            (create — resolves variations, estimates cost)
   └─▶ status: planned      children created, nothing executes, review freely
POST /v1/orders/{id}/start  (the explicit go)
   └─▶ status: running      children stream through the executor
   └─▶ status: completed | failed | cancelled

Creating an order plans it — variations resolve into children, the whole batch is estimated and checked against budgets — but nothing executes until the explicit start. Review the plan, then commit.

The order record

an order, settledjson

{
  "id": "order-046b1a54",
  "workflowId": "generate-clip-art-asset-v2",
  "status": "completed",
  "targetCount": 50,
  "counts": { "planned": 0, "running": 0, "succeeded": 50, "failed": 0, "skipped": 0 },
  "budgetLimitUsd": 3.50,
  "budgetEnforcementMode": "hard_stop",
  "estimatedCostUsd": 2.65,
  "actualCostUsd": 2.73
}

What each child carries

Field	Meaning
`parentOrderId`	The order that fanned it out — list children with GET /v1/runs?parentOrderId=.
`orderDedupeKey`	A deterministic key per planned variation: re-running an order skips already-succeeded keys instead of regenerating.
`workerId`	Set when a worker’s shift placed the order — the whole batch is attributed.

Budgets

Orders take their own cap (budgetLimitUsd, default hard_stop) on top of workspace and project budgets. Enforcement happens pre-flight on estimates: a batch that would breach never starts.