Skip to main content
A run is one task you send to Millwork; the API calls it an execution. A live submission returns 202 with an execution_id. Millwork records accepted as its first event and charges the platform fee at acceptance. If a model fits, the response status is queued. If none fits, it is already failed, and Millwork returns the fee and quota automatically. A test run (the API calls it Echo, mode: "echo") finishes during the submit request. It calls no model and has no platform fee or model cost. Read its returned final status; a successful test returns completed. Four statuses are final: completed, failed, cancelled, and expired. Only a completed live run has a result. Every run that reaches a final status has a receipt, the record of what ran without the prompt or the output. This diagram shows the statuses you can receive for a live run, including a submission that fails because no model fits. accepted is the run’s first event. It appears in the API’s status list, but you will not read it back as a status: Millwork moves the run to queued or failed in the same step, before you can read it.

​
What each live-run status means

​
Which runs you can cancel

You can cancel a run that has not reached a final status:
Expected result: 202 with status cancelled. If the run already reached a final status, the request is refused; fetch the status again and keep its result or receipt. Cancelling stops only work that has not started. Stop a run has the full command with error handling.

​
When the platform fee is charged and when it comes back

Cancelling avoids model usage that has not started, but a run you cancel keeps its fee and still counts toward your quota. The one exception: when Millwork fails a run before any model attempt starts (no model could serve it, the output check was unavailable, or the selected model was not ready), it returns the fee and the quota automatically. Read when the platform fee is charged.

​
Submit once

Send a request key in the Idempotency-Key header with each new run. If the network fails during submission, send the same request again with the same key and the same body. Millwork returns the original run instead of creating another.

​
Wait for a final status

Poll links.status until the run ends. It is the status endpoint for the run:
Do not submit a new run because the first one is still queued or running.

​
Read the result or the failure details

  • After a live run reaches completed, fetch the result and the receipt.
  • After failed, read the status, the events, then the receipt.
  • After cancelled or expired, read the status and the receipt.
  • A test run never has a result.
For a complete command sequence, use Run a model.