Docs
Uploading test runs
A board can keep its project's test results. Upload one record per run and the board's
Test trends view charts them, and your agent reads the same history through
the test_trends MCP tool.
1. Get an upload token
Uploads authenticate with an API token, not your sign-in. Use one token per machine or CI
job, limited to the board it reports to, with the test-runs:write scope. Then
revoking one uploader leaves the others running. A token never grants more than you can do
yourself, so you must be able to write the board.
Tokens aren't self-serve yet. There is no button to mint one today. Ask for one along with your board, the same way you get its MCP config.
2. Store it outside the repo
Anyone holding the token can upload runs to the board as you until it expires or is
revoked. Keep it in your shell, a gitignored .env.local, or a CI secret:
TADA_TOKEN=tada_…
TADA_TEST_RUNS_BOARD=<slug>
The board's empty Test trends view shows this block with its slug already filled in.
3. Upload one record per run
After each run, POST its summary to the API host. Note that this is
tada-api.onrender.com, not the app's address:
curl -X POST https://tada-api.onrender.com/api/projects/<slug>/test-runs \
-H "Authorization: Bearer $TADA_TOKEN" -H "Content-Type: application/json" \
-d @run.json
An upload failure must never fail the test run. Queue the record and try again on the next run.
The record
One JSON object. A field the API doesn't know is refused. The ones most uploaders send:
startedAt,durationMs- When the run started (ISO 8601) and how long it took, in milliseconds.
machine,source-
A stable name for the machine that ran it, and
"local"or"ci". passed,failed,flaky,skipped- Test counts. All four are required; send 0 for none.
scope,suiteSize-
Optional.
"full"when the run selected every test,"partial"when it was narrowed (a filter, one file, a shard). SendsuiteSizeonly on a full run, where it must equal the four counts added up. sha,branch- Optional. The commit and branch the run tested.
series-
Optional. A name for a second kind of run on the same board, such as
typecheckorbuild: lowercase letters, digits and hyphens, up to 40 characters. Each series is charted and kept apart. Leave it out for the board's main suite.
What the API answers
201- Stored.
400- The record failed validation;
issueslists each bad field. Retrying sends the same mistake. 401- The token is mistyped, expired or revoked. Get a new one.
403- The token lacks
test-runs:write, or its owner can't write this board. 404- No such board, or the token is limited to other boards. Check the slug.
413- The record is over 256 KB.
429- Too many uploads in ten minutes. Wait for
Retry-After, then send the queue.
A board keeps 90 days of runs per series: never fewer than the newest 100, and never more than the newest 500.