---
title: "Test runs and credits"
description: "A test run is a real run that calls real tools and spends real credits."
url: https://docs.spinrun.ai/build/test-runs
markdown_url: https://docs.spinrun.ai/build/test-runs.md
---

# Test runs and 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 [#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 [#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.

## Related [#related]

* [Untrusted output](https://docs.spinrun.ai/build/untrusted-output.md)
* [CLI: agent test](https://docs.spinrun.ai/cli/agent-test.md)
* [REST: test an agent](https://docs.spinrun.ai/api/runs/test-agent.md)