Run a model

Goal: Run one live task on a model your organization can use, with public or test data. You are done when: the run reaches completed, the result contains model output, and the receipt identifies the saved model that ran. Choose a model, send it one task with a budget and time limit, then read its answer. This walkthrough keeps the run on the model and provider you choose. After a completed run, read two records. The result holds the model output. The receipt records which saved model ran and what it used. It never contains your prompt or the output. A run is one task you send to Millwork; the API calls a run an execution. A saved model is a catalog model you added to your organization; the API calls a saved model an arm.

What a live run costs

Platform fee: charged when Millwork accepts the run, not when it completes. A run you cancel keeps its fee.
Model usage: a separate cost. For a model Millwork provides, Millwork deducts recorded usage from your credit. With your provider account, the provider bills usage under your account’s terms.

A live run needs credit and quota. Your quota is the number of runs your organization may submit per calendar month (UTC), and how many may run at once. See your balance in Billing. Read Model access and billing for cancellation and the one case where Millwork returns the fee. Want to check your key first without paying anything? Make your first API call. It uses a test run (the API calls it Echo, mode: "echo"). A test run does not call a model, so it has no platform fee and no model cost. It still counts toward your quota. This diagram shows the requests your app sends, the moment the platform fee is charged, and the two records your app reads at the end.

Before you begin

Your organization is approved for the private preview.
Your Millwork API key is configured for the organization you want to use.
You have curl and jq.
Your account has credit and quota for one live run.

export MILLWORK_API_URL="https://api.getmillwork.dev/v1"
export MILLWORK_API_KEY="$SOLVERAPI_API_KEY"
export RUN_SUFFIX="$(date +%s)"

RUN_SUFFIX makes each request key unique. A request key is the value you send in the Idempotency-Key header so a retry does not start the work twice.

Use only public information or test data created for this run. Read Data and credentials before sending a live task.

Never paste a provider key into a saved model, a run request, a support message, or a documentation playground. For a model Millwork provides, your Millwork API key is enough. If you choose your own provider account, follow its connection setup.

Choose a model from your catalog

Your catalog lists the models your organization can use now. If you came from Connect a provider account, keep CONNECTION_ID in this terminal. The code below limits the list to that connection. Otherwise it shows the whole catalog.

if ! curl --fail-with-body \
  --header "Authorization: Bearer $MILLWORK_API_KEY" \
  --output catalog-response.json \
  "$MILLWORK_API_URL/model-catalog"; then
  echo "Read catalog-response.json before continuing." >&2
  exit 1
fi

jq --arg connection "${CONNECTION_ID:-}" '
  if $connection == "" then .
  else .models |= map(select(.connection.connection_id == $connection)) end
' catalog-response.json > catalog.json

jq -r '.models | to_entries[] |
  "\(.key): \(.value.arm_registration_template.display_name // .value.model.model_key) | provider: \(.value.source.source_id) | access: \(.value.connection.commercial_owner)"' \
  catalog.json

Expected result: one line per model, numbered from 0. access: customer means the model runs through your own provider account, so your provider bills the model usage. access: millwork means Millwork provides the model and deducts its recorded usage from your credit.Pick one row and keep its number for the next step:

export MODEL_INDEX=0
jq --argjson i "$MODEL_INDEX" -e '.models[$i]' catalog.json

If the catalog is empty, ask support about models available to your organization. Connecting your own provider account is a separate option.

Save the model to your organization

Each catalog entry carries arm_registration_template, the exact body for this request. Send it unchanged. Millwork rejects a saved model whose settings go beyond that template.

jq --argjson i "$MODEL_INDEX" \
  '.models[$i].arm_registration_template' \
  catalog.json > arm-request.json

if ! curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $MILLWORK_API_KEY" \
  --header "Content-Type: application/json" \
  --data @arm-request.json \
  --output arm-response.json \
  "$MILLWORK_API_URL/arms"; then
  echo "The model was not confirmed saved. Read arm-response.json before continuing." >&2
  exit 1
fi

ARM_ID="$(jq -er '.arm_id | strings | select(length > 0)' arm-response.json)" || exit 1
jq -e '.status == "ready"' arm-response.json >/dev/null || exit 1

Expected result: 201 with an arm_id and "status": "ready". If the status is degraded or disabled, read status_reason and choose another catalog row.Keep ARM_ID. The next request sends it as routing.required_arm_id to use this saved model and its provider account. If the model is unavailable, Millwork refuses the request; it does not substitute another model.If the response was lost, send the same registration again with the same request key in the Idempotency-Key header and Millwork returns the saved model it already created. Without a request key, check GET /v1/arms for the saved model before sending the registration again.

Submit the run

Send the task and your limits. Millwork charges the platform fee the moment it accepts the run. Model usage is a separate cost, described in Model access and billing. A live run needs credit and quota.What each limit means:

data_classes is the kind of data you allow. Use public for public information and sandbox for examples you invented for testing.
max_cost_usd is the model-usage budget. Once recorded spend reaches it, Millwork starts no further provider calls. A call already started can finish above this amount. The platform fee is separate.
max_runtime_s is the run’s time limit.
on_eval lists what Millwork may do after the output check. An empty list means it does nothing more on its own.

An output check is a check applied to the run’s output; the API calls it a verifier (verifier_id). If you do not send a verifier_id, a basic check confirms only that output is present. To connect a check you already run, follow Connect an output check.

jq -n --arg arm "$ARM_ID" '{
  mode: "live",
  task: {
    objective: "Explain what an API receipt is in one short sentence.",
    inputs_ref: { kind: "inline_json", json: { audience: "API developers" } }
  },
  policy: {
    data_classes: ["public"],
    budget: { max_cost_usd: 1, max_runtime_s: 60 },
    on_eval: []
  },
  routing: { required_arm_id: $arm }
}' > run-request.json

if ! curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $MILLWORK_API_KEY" \
  --header "Idempotency-Key: run-$RUN_SUFFIX" \
  --header "Content-Type: application/json" \
  --data @run-request.json \
  --output execution.json \
  "$MILLWORK_API_URL/executions"; then
  echo "The request failed. Read execution.json before retrying." >&2
  exit 1
fi

EXECUTION_ID="$(jq -er '.execution_id' execution.json)" || exit 1

Expected result: 202 with an execution_id, "status": "queued", "mode": "live", and links to the status, events, and receipt. Keep the execution_id. Every status, event, result, receipt, and support request uses it.If the response was lost, repeat this request with the same RUN_SUFFIX and body. Changing the request key starts a new run.If the API returns insufficient_credit, add credit under Billing & plan and send the request again with a new request key.

Wait for a final status

Millwork records accepted as the run’s first event, then the run moves through queued, running, and progress. Poll until it reaches one of the four final statuses: completed, failed, cancelled, or expired. Do not submit the task again while it is running.

STATUS="unknown"
DEADLINE=$((SECONDS + 90))

while [ "$SECONDS" -lt "$DEADLINE" ]; do
  if ! curl --fail-with-body \
    --header "Authorization: Bearer $MILLWORK_API_KEY" \
    --output execution-status.json \
    "$MILLWORK_API_URL/executions/$EXECUTION_ID"; then
    echo "The status request failed. Read execution-status.json before retrying." >&2
    exit 1
  fi

  STATUS="$(jq -r '.status' execution-status.json)"

  case "$STATUS" in
    completed|failed|cancelled|expired) break ;;
    *) sleep 2 ;;
  esac
done

if [ "$STATUS" != "completed" ] &&
   [ "$STATUS" != "failed" ] &&
   [ "$STATUS" != "cancelled" ] &&
   [ "$STATUS" != "expired" ]; then
  echo "The run did not finish within 90 seconds. Keep the run ID and check it again later." >&2
  exit 1
fi

echo "$STATUS"

Expected result: completed. Keep the execution_id for the last step. A run that is still in progress after 90 seconds is not lost. Check it again later with the same id.

Read the result and the receipt

Only a completed live run has a result. Every run that reaches a final status has a receipt.

if [ "$STATUS" = "completed" ]; then
  curl --fail-with-body \
    --header "Authorization: Bearer $MILLWORK_API_KEY" \
    --output result.json \
    "$MILLWORK_API_URL/executions/$EXECUTION_ID/result"
fi

curl --fail-with-body \
  --header "Authorization: Bearer $MILLWORK_API_KEY" \
  "$MILLWORK_API_URL/receipts/$EXECUTION_ID" \
  | tee receipt.json

Read your answer after completed:

if [ "$STATUS" = "completed" ]; then
  jq -er '.final_text | strings | select(length > 0)' result.json
fi

Expected result: your model’s answer. result.json may also contain an expiry time in retention_expires_at. receipt.json records which saved model ran (slices[0].route.selected_arm), the model usage (slices[0].cost and totals.usd), the platform fee on its own line (totals.platform_fee_usd), and the output check that applied. It does not contain your prompt or the output. A verifier named vrf_builtin_baseline is the built-in presence check; it confirms output exists, not that the answer is correct.If the run failed, read its events before retrying:

curl --fail-with-body \
  --header "Authorization: Bearer $MILLWORK_API_KEY" \
  "$MILLWORK_API_URL/executions/$EXECUTION_ID/events"

Check your work

The saved model is ready.
The run reached completed.
result.json contains model output in final_text.
receipt.json identifies the selected saved model, without the prompt or output.

Read the selected model from the receipt:

jq '.slices[0].route.selected_arm' receipt.json

The selected arm should equal the ARM_ID you saved. For a catalog model, compare the requested and provider-reported model names:

jq '{
  requested: .model_provenance.requested.upstream_ref,
  provider_reported: .model_provenance.resolved.upstream_ref,
  provider: .model_provenance.source.source_id
}' result.json

requested is what Millwork asked for. provider_reported is what the provider said it ran; it can be a dated or more specific name. The receipt carries the same facts in slices[0].model_provenance. If Millwork selected a model your administrator saved directly with a provider model ID, the result’s model_provenance is null and the receipt omits it. The saved-model ID and usage are still recorded. Do not infer a provider-reported model from the saved model’s name.

Common fixes

What happened	What to do
The catalog is empty	Ask support about models available to your organization. Connecting your own provider account is a separate option.
The saved model is `degraded` or `disabled`	Read `status_reason` in the response and choose another catalog row.
`insufficient_credit`	Add credit in Billing, then submit again with a new request key. No fee was charged.
`idempotency_conflict`	You reused a request key with a different body. Send the original body, or use a new key for new work.
The run `failed`	Read its events and receipt before retrying. The platform fee stays unless Millwork failed the run before any model attempt.
There is no result	Check the final status. Only a completed live run has a result.

For retry rules and every error code, read Errors and retries.

Send another task

Keep the saved model, change the objective in run-request.json, and choose a new RUN_SUFFIX before submitting new work. Reuse the original request key only to recover the original request. To change models, choose and save another catalog row, then use its new ARM_ID in the next request. Keeping routing.required_arm_id ensures the request uses that model and payer. Automatic model selection is an option described in Model access and billing.

Your provider account

Run through a provider account your organization already pays for.

Get started

Provide models

Build

Build safely

SDK and MCP

What a live run costs

Before you begin

Check your work

Common fixes

Send another task

Your provider account

​What a live run costs

​Before you begin

​Check your work

​Common fixes

​Send another task

Your provider account

What a live run costs

Before you begin

Check your work

Common fixes

Send another task