Test runs
Mark a run as a test to prove your setup works. It is answered like any run, but it stores nothing, costs nothing, and each account may start 100 a day.
In short
Send "test_run": true on resolve and the run is a test: it gets the same answer as any run, but nothing is learned from it, nothing is billed, and the loop-closure funnel leaves it out. Each account may start 100 test runs a day.
A test run is an ordinary run that you mark. Use it while you wire an agent up, in your own checks, or after a change, so that proving the loop works does not teach your agent from made-up tasks or inflate the numbers your team reads.
What a test run does
Every call in the loop behaves as it does for any run, except where this table says otherwise.
| Call | For a test run |
|---|---|
resolve | Answered as usual, with the same learnings and claims. Charged nothing. |
observe | Accepted and finished as usual, but no learning and no claim is written from it. |
reinforce | Closes the run. No learning is credited or demoted. |
decline | Closes the run. Nothing is counted for or against the learnings it was offered. |
Because a test run writes no claims, you can put realistic details in its episode without them reaching your agent's claims.
GET /funnel leaves test runs out of its loop-closure figures.
Mark a run
Add test_run to resolve. Leave it out of observe and reinforce: they take the mark from the resolve that opened the run.
| Surface | How to mark a run |
|---|---|
| REST | "test_run": true on POST /resolve. |
| MCP server | test_run: true on the resolve tool. complete_run takes no test_run and inherits the mark. |
The Python and TypeScript clients and the Claude Code hook have no test_run argument. To send test runs from an agent they drive, call REST or the MCP server.
The daily allowance
Each account may start 100 test runs a day, counted from UTC midnight and across all its agents and keys. The 101st is refused with 403, and the body says when the day resets:
{
"detail": {
"code": "test_run_limit",
"message": "This account has used its 100 test runs for today. Test runs are refused until 2026-11-15T00:00:00+00:00.",
"limit": 100,
"resets_at": "2026-11-15T00:00:00+00:00"
}
}A run takes its place when it opens, and keeps it for its whole life, so a test run that is closed the next day is not counted again and is not refused. Sending resolve again for a run that already holds a place takes no new one. A test run whose first call is observe or reinforce, because it was never resolved, takes a place the same way.
Through MCP, a refused test run answers with status quota_exceeded and that message, and no run_id. A test run that fails for another reason also returns no run_id: invalid_request when the request was refused as malformed, retry_advised otherwise, so the host sends the resolve again rather than completing a run that does not exist.
When the mark is stated twice
The first call that reaches a run decides whether it is a test, and nothing changes that later. Leaving test_run out is never a contradiction; repeating the same value is allowed; stating the opposite is refused.
Opening resolve | Later resolve, observe or reinforce | Result |
|---|---|---|
test_run: true | omitted or true | A test run. |
test_run: true | false | Refused with 409. |
| omitted | true | Refused with 409. |
| omitted | omitted or false | An ordinary run. |
A run that was never resolved, or whose record has expired, takes the value its observe or reinforce states, and is ordinary if that is left out. To turn an ordinary run into a test, start again with a new run_id.
The refusal answers 409, before any work is done:
{
"detail": {
"code": "test_run_mismatch",
"message": "run 'freight-booking-agent:setup-check-1' was resolved with test_run=True; this call states test_run=False"
}
}Fix it by leaving test_run out of the write-back. Sending the same call again does not help.
Reading the result
GET /learning-runs/{run_id}/status marks a test run. It answers test_run: true, every count reads zero from the start, and zero_reason is test_run, before and after the run's observe. The run reaches finished as any run does.