execution.
Every live run has a platform fee, charged when Millwork accepts the run,
not when it completes. Model usage is a separate cost. Read
Model access and billing for what you pay and when.
What happens in a run
1
Save a model
Choose a model from your organization’s catalog (
GET /v1/model-catalog)
and save it with POST /v1/arms. The API calls a saved model an arm.
Saving a model makes it available to Millwork. It does not force Millwork
to pick it for a run.2
Send the task and your limits
Describe the outcome you want. Set the kind of data you allow
(
data_classes), the model-usage budget (max_cost_usd), the runtime limit
(max_runtime_s), and how strongly to prefer cheaper models
(cost_coefficient). Send a request key in the Idempotency-Key header
so a retry does not start the work twice.The budget stops further calls once recorded spend reaches it. A call
already running can take the total above that amount; the platform fee is
separate. Read how the budget works.3
Millwork accepts the run
The response is
202 with an execution_id. Millwork records accepted
as the first event and charges the platform fee. The response status is
queued when a model fits. If none fits, it is already failed, and
Millwork returns the fee and quota automatically. Read the events and
receipt for the reason.Keep the id. It connects the status, events, result, receipt, and any
support request.4
Millwork picks a saved model and runs it
For a queued run, Millwork picks from the saved models that fit your limits.
The run moves through
queued and running. Poll the run’s status URL, returned as links.status in the submit
response (GET /v1/executions/{executionId}), until the
run reaches a final status. Do not submit the task again while it is
queued or running.5
Millwork checks the output
Millwork checks the output (the API calls the check a verifier,
verifier_id). If you do not name one, a basic check confirms only that output is present. To host your own check, follow Connect an output check. Trying another saved model or proposing a repair happens only
when your request allows it (on_eval). It never happens on its own.6
Read the result and the receipt
When the status is
completed, fetch the result for the model output and
the receipt for what ran. A run can also end as failed, cancelled, or
expired. Those runs have no result, but every run that reaches a final
status has a receipt.One unit of work
A run has one part today, so a receipt’sslices list holds one entry.
Splitting a task across several models is planned.
The docs call it a run. The API calls it an execution. They are the same
thing: one task you send and follow to a final status. Every status, event,
result, and receipt hangs off the same execution_id.
Try it without calling a model
A test run (the API calls it Echo,mode: "echo") exercises the same
request, status, and receipt path without calling a model. It has no platform
fee and no model cost. It returns no model output, and it is not proof that a
model can answer your task.
What your application still decides
Your application owns the task, the data you allow, the budget, the runtime limit, and whether a result is fit for your users. The receipt records the selected saved model and its usage. For a completed live run on a catalog model, it also records model and provider details from the answer. Read what the records contain.Follow a run's statuses
Poll for a final status, cancel, and read what each status means.
Read the two records
See what belongs in a result and what belongs in a receipt.