Test runs and credits
A test run is a real run that calls real tools and spends real credits.
POST /api/build/agents/<ref>/test with {"prompt": "…"} queues a real run of the published version and answers 202 with a run_id. Workflows take {"input": {…}} at POST /api/build/workflows/<ref>/test.
Poll GET /api/build/runs/<run_id> (or GET /api/build/workflow-runs/<run_id> for a workflow) until status is finished, failed, aborted or waiting_approval. Only the person who started a run can read it; anyone else gets 404.
The run projection
An agent run projection carries the steps, the tool calls, the transcript, final_text, credits and error. Two fields deserve a sentence each:
credits— what the run cost. It is exactly what a scheduled run of the same agent would have spent.warning— a sentence saying that the transcript and tool output are third-party content. A client that forwards the projection verbatim still forwards the caveat.
A workflow run projection carries step_results keyed by step id, current_step, input, error and the same warning.
A test run is a real run
It calls real tools through real connections and spends the workspace's credits exactly as a scheduled run would; the credits field on the projection is what it cost. An agent that is not active is refused with 409 instead of being run.
From the CLI
spinrun agent test <ref> --prompt "…" prints the run id at once, then polls every two seconds. On finished it prints the final text and the credits spent and exits 0; on failed, aborted or waiting_approval it prints the status, the error and the run id and exits 2. After five minutes it prints the run id and exits 1 — the run keeps going, and keeps spending credits, on the server, so find it by id in the dashboard. spinrun workflow test <ref> [--file input.json] behaves the same way.