Test runs

A test run is one clanker run of a product's Playwright tests against its deployment in an environment, numbered per workspace. Start a run, upload each test's files, then finish it with every test's first attempt. A retry runs the failed tests again on the same commit, and a failed test that passes every retry attempt counts as flaky.

The TestRun object

A test run with its retries and every test with its attempts.

Attributes

idstringRequired

Unique ID of the test run.

numbernumberRequired

The run's number, counting up from 1 in each workspace, such as 1289.

urlstringRequired

The run's page on the website.

statestringRequired

running until its publisher finishes it as finished or interrupted. One still running after 6 hours becomes interrupted.

One ofrunningfinishedinterrupted

resultnullable stringRequired

passed when the run has no error and no failed test, otherwise failed. Flaky tests count as passed. Null while running and for interrupted runs.

One ofpassedfailed

countsobjectRequired

How many tests have each status.

passRatenullable numberRequired

(passed + flaky) ÷ (tests − skipped), from 0 to 1. Null while running or when no test counts.

firstAttemptPassRatenullable numberRequired

Tests that passed on attempt 1 ÷ (tests − skipped), from 0 to 1. Retries never change it. Null while running or when no test counts.

errornullable stringRequired

What failed outside the tests, such as a web server that did not start, or No tests ran. A run with an error is failed and cannot be retried.

productobjectRequired

The product the run tested.

environmentobjectRequired

The environment the run tested.

baseUrlstringRequired

The URL the tests ran against.

deploymentBaseUrlnullable stringRequired

The deployment's URL when the run started, or null. It differs from baseUrl when clanker run --base-url overrode it.

deploymentVersionnullable stringRequired

The deployment's version when the run started, or null.

gitobjectRequired

The commit the run tested.

machineobjectRequired

The computer that ran the tests.

coveragenullable stringRequired

The coverage level the run selected, or null when it selected none.

One ofcriticalacceptanceregressionexhaustive

cleanupnullable objectRequired

The run's scope and what deleting it reported, or null when the deployment had no Fixture API.

publishedByobjectRequired

Who published a run or a retry: a person, an account API key, or one since removed.

startedAtstringRequired

When the run started, as an ISO 8601 timestamp.

finishedAtnullable stringRequired

When the run finished or was marked interrupted, as an ISO 8601 timestamp, or null while running.

durationMsnumberRequired

How long the run took, in milliseconds, as its publisher reported. 0 while running.

retriesarray of objectsRequired

The run's retries, oldest first.

testsarray of objectsRequired

Every test, failed first, then flaky, passed and skipped, by title.

The TestRun object

{  "id": "Tr8KcW3nPx5Q",  "number": 1289,  "url": "https://clankertest.com/w/acme/test-runs/1289",  "state": "finished",  "result": "passed",  "counts": {    "total": 2,    "passed": 1,    "flaky": 1,    "failed": 0,    "skipped": 0  },  "passRate": 1,  "firstAttemptPassRate": 0.5,  "error": null,  "product": {    "slug": "storefront",    "name": "Storefront"  },  "environment": {    "slug": "staging",    "name": "Staging",    "class": "non-production"  },  "baseUrl": "https://staging.acme.dev",  "deploymentBaseUrl": "https://staging.acme.dev",  "deploymentVersion": "9f2c41e",  "git": {    "branch": "web-31-docs-search",    "sha": "9f2c41e7b8a3d5c6f1e0b2a4d6c8e0f1a3b5c7d9",    "dirty": false,    "subject": "Add docs search"  },  "machine": {    "hostname": "maya-mbp",    "platform": "darwin"  },  "coverage": null,  "cleanup": {    "scope": "scp_7h2k9q2m4x1a",    "expiresAt": "2026-10-14T15:40:00.000Z",    "status": "complete",    "deleted": 214,    "remaining": 0  },  "publishedBy": {    "kind": "user",    "name": "Maya Patel",    "email": "maya@acme.dev"  },  "startedAt": "2026-10-14T09:40:00.000Z",  "finishedAt": "2026-10-14T09:42:31.000Z",  "durationMs": 151230,  "retries": [    {      "number": 1,      "state": "finished",      "requiredPasses": 2,      "testCount": 1,      "flakyCount": 1,      "baseUrl": "https://staging.acme.dev",      "gitSha": "9f2c41e7b8a3d5c6f1e0b2a4d6c8e0f1a3b5c7d9",      "cleanup": {        "scope": "scp_q8w3e5r7t9y2",        "expiresAt": "2026-10-14T15:40:00.000Z",        "status": "complete",        "deleted": 12,        "remaining": 0      },      "publishedBy": {        "kind": "user",        "name": "Maya Patel",        "email": "maya@acme.dev"      },      "startedAt": "2026-10-14T09:44:05.000Z",      "finishedAt": "2026-10-14T09:44:22.000Z"    }  ],  "tests": [    {      "caseId": "checkout-applies-coupon",      "title": "checkout › applies a coupon",      "file": "checkout.spec.ts",      "coverage": "critical",      "testKind": "behavior",      "priority": null,      "status": "flaky",      "durationMs": 4105,      "errorMessage": "Timed out 5000ms waiting for expect(locator).toHaveText(\"$45.00\")",      "files": [        "case.md",        "spec.ts"      ],      "attempts": [        {          "number": 1,          "retry": null,          "status": "failed",          "durationMs": 30412,          "startedAt": "2026-10-14T09:40:12.000Z",          "errorMessage": "Timed out 5000ms waiting for expect(locator).toHaveText(\"$45.00\")",          "errorStack": "Error: Timed out 5000ms waiting for expect(locator).toHaveText(\"$45.00\")\n    at checkout.spec.ts:24:41",          "files": [            "video.webm",            "trace.zip",            "screenshot-1.png"          ]        },        {          "number": 2,          "retry": 1,          "status": "passed",          "durationMs": 4210,          "startedAt": "2026-10-14T09:44:07.000Z",          "errorMessage": null,          "errorStack": null,          "files": []        },        {          "number": 3,          "retry": 1,          "status": "passed",          "durationMs": 4105,          "startedAt": "2026-10-14T09:44:13.000Z",          "errorMessage": null,          "errorStack": null,          "files": []        }      ]    },    {      "caseId": "docs-search-finds-guides",      "title": "docs › search finds guides",      "file": "docs.spec.ts",      "coverage": "acceptance",      "testKind": "journey",      "priority": null,      "status": "passed",      "durationMs": 6820,      "errorMessage": null,      "files": [        "case.md",        "spec.ts"      ],      "attempts": [        {          "number": 1,          "retry": null,          "status": "passed",          "durationMs": 6820,          "startedAt": "2026-10-14T09:40:12.000Z",          "errorMessage": null,          "errorStack": null,          "files": []        }      ]    }  ]}

List test runs

GET/v1/workspaces/{slug}/test-runs

Returns the workspace's runs, newest first, 50 per page. Send the response's nextCursor as cursor for the next page.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

Query parameters

productstring

Only runs of this product, by slug.

environmentstring

Only runs in this environment, by slug.

resultstring

Only runs that passed or failed, or flaky for runs with at least one flaky test.

One ofpassedfailedflaky

qstring

Matches part of the branch or the commit subject, or the start of a commit SHA.

commitstring

Only runs of this full commit SHA.

minestring

true for only the runs you published.

Always true

cursorstring

The nextCursor of the previous page.

Returns

Returns an object with these fields. Status 200.

runsarray of objectsRequired

Up to 50 runs, newest first.

nextCursornullable numberRequired

The cursor for the next page, or null on the last page.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

GET/v1/workspaces/{slug}/test-runs

1curl https://api.qa.clankership.net/v1/workspaces/acme/test-runs \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "runs": [    {      "id": "Tr8KcW3nPx5Q",      "number": 1289,      "url": "https://clankertest.com/w/acme/test-runs/1289",      "state": "finished",      "result": "passed",      "counts": {        "total": 2,        "passed": 1,        "flaky": 1,        "failed": 0,        "skipped": 0      },      "passRate": 1,      "firstAttemptPassRate": 0.5,      "error": null,      "product": {        "slug": "storefront",        "name": "Storefront"      },      "environment": {        "slug": "staging",        "name": "Staging",        "class": "non-production"      },      "baseUrl": "https://staging.acme.dev",      "deploymentBaseUrl": "https://staging.acme.dev",      "deploymentVersion": "9f2c41e",      "git": {        "branch": "web-31-docs-search",        "sha": "9f2c41e7b8a3d5c6f1e0b2a4d6c8e0f1a3b5c7d9",        "dirty": false,        "subject": "Add docs search"      },      "machine": {        "hostname": "maya-mbp",        "platform": "darwin"      },      "coverage": null,      "cleanup": {        "scope": "scp_7h2k9q2m4x1a",        "expiresAt": "2026-10-14T15:40:00.000Z",        "status": "complete",        "deleted": 214,        "remaining": 0      },      "publishedBy": {        "kind": "user",        "name": "Maya Patel",        "email": "maya@acme.dev"      },      "startedAt": "2026-10-14T09:40:00.000Z",      "finishedAt": "2026-10-14T09:42:31.000Z",      "durationMs": 151230    }  ],  "nextCursor": null}

Start a test run

POST/v1/workspaces/{slug}/test-runs

Starts a running run of a product's deployment in an environment and records the deployment's URL and version. When the deployment has a Fixture API, the run gets a scope and a fixture token to create its test data with. While it runs, its publisher uploads each file as the raw body of PUT /v1/workspaces/{slug}/test-runs/{run}/files/{path}, with Content-Length and at most 100 MB, deletes the scope, then finishes the run. Viewers cannot publish runs, and an archived product or environment or a missing deployment fails the request.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

Body parameters

productstringRequired

The product to test, by slug, such as storefront.

environmentstringRequired

The environment it is deployed to, by slug, such as staging.

baseUrlstringRequired

The URL the tests run against, usually the deployment's baseUrl.

fixtureUrlnullable string

Use this Fixture API instead of the deployment's, such as a local server on another port. The fixture token is only valid there.

gitobjectRequired

The commit being tested.

machineobjectRequired

The computer running the tests.

selectionobjectRequired

Which tests the run selects.

Returns

Returns an object with these fields. Status 201.

numbernumberRequired

The run's number in the workspace. Later calls name the run by it.

urlstringRequired

The run's page on the website.

fixturenullable FixtureGrant objectRequired

The run's scope and fixture token, or null when the deployment has no Fixture API.

semaphoresobjectRequired

Where a run or retry takes semaphore leases, and the run token it takes them with.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

POST/v1/workspaces/{slug}/test-runs

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/test-runs \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "product": "storefront",6    "environment": "staging",7    "baseUrl": "https://staging.acme.dev",8    "git": {9      "branch": "web-31-docs-search",10      "sha": "9f2c41e7b8a3d5c6f1e0b2a4d6c8e0f1a3b5c7d9",11      "dirty": false,12      "subject": "Add docs search"13    },14    "machine": {15      "hostname": "maya-mbp",16      "platform": "darwin"17    },18    "selection": {19      "coverage": null,20      "folders": [],21      "caseIds": []22    }23  }'

Response201

{  "number": 1289,  "url": "https://clankertest.com/w/acme/test-runs/1289",  "fixture": {    "scope": "scp_7h2k9q2m4x1a",    "token": "eyJhbGciOiJFZERTQSIsImtpZCI6ImZ4XzEifQ.eyJzY29wZSI6InNjcF83aDJrOXEybTR4MWEifQ.c2lnbmF0dXJl",    "url": "https://staging.acme.dev/fixtures",    "expiresAt": "2026-10-14T15:40:00.000Z"  },  "semaphores": {    "url": "https://api.clankertest.com/v1/workspaces/Wk7Qm2RtXa9L/semaphores",    "token": "eyJhbGciOiJFZERTQSIsImtpZCI6ImZ4XzEifQ.eyJraW5kIjoicnVuIiwicnVuIjoxMjg5fQ.c2lnbmF0dXJl",    "expiresAt": "2026-10-14T15:40:00.000Z"  }}

Get a test run

GET/v1/workspaces/{slug}/test-runs/{run}

Returns one run with its retries and every test with its attempts. Download a stored file with GET /v1/workspaces/{slug}/test-runs/{run}/files/{path}, which accepts a Range header.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

runintegerRequired

The run's number in the workspace, such as 1289.

Returns

Returns the TestRun object. Status 200.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

GET/v1/workspaces/{slug}/test-runs/{run}

1curl https://api.qa.clankership.net/v1/workspaces/acme/test-runs/{run} \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "id": "Tr8KcW3nPx5Q",  "number": 1289,  "url": "https://clankertest.com/w/acme/test-runs/1289",  "state": "finished",  "result": "passed",  "counts": {    "total": 2,    "passed": 1,    "flaky": 1,    "failed": 0,    "skipped": 0  },  "passRate": 1,  "firstAttemptPassRate": 0.5,  "error": null,  "product": {    "slug": "storefront",    "name": "Storefront"  },  "environment": {    "slug": "staging",    "name": "Staging",    "class": "non-production"  },  "baseUrl": "https://staging.acme.dev",  "deploymentBaseUrl": "https://staging.acme.dev",  "deploymentVersion": "9f2c41e",  "git": {    "branch": "web-31-docs-search",    "sha": "9f2c41e7b8a3d5c6f1e0b2a4d6c8e0f1a3b5c7d9",    "dirty": false,    "subject": "Add docs search"  },  "machine": {    "hostname": "maya-mbp",    "platform": "darwin"  },  "coverage": null,  "cleanup": {    "scope": "scp_7h2k9q2m4x1a",    "expiresAt": "2026-10-14T15:40:00.000Z",    "status": "complete",    "deleted": 214,    "remaining": 0  },  "publishedBy": {    "kind": "user",    "name": "Maya Patel",    "email": "maya@acme.dev"  },  "startedAt": "2026-10-14T09:40:00.000Z",  "finishedAt": "2026-10-14T09:42:31.000Z",  "durationMs": 151230,  "retries": [    {      "number": 1,      "state": "finished",      "requiredPasses": 2,      "testCount": 1,      "flakyCount": 1,      "baseUrl": "https://staging.acme.dev",      "gitSha": "9f2c41e7b8a3d5c6f1e0b2a4d6c8e0f1a3b5c7d9",      "cleanup": {        "scope": "scp_q8w3e5r7t9y2",        "expiresAt": "2026-10-14T15:40:00.000Z",        "status": "complete",        "deleted": 12,        "remaining": 0      },      "publishedBy": {        "kind": "user",        "name": "Maya Patel",        "email": "maya@acme.dev"      },      "startedAt": "2026-10-14T09:44:05.000Z",      "finishedAt": "2026-10-14T09:44:22.000Z"    }  ],  "tests": [    {      "caseId": "checkout-applies-coupon",      "title": "checkout › applies a coupon",      "file": "checkout.spec.ts",      "coverage": "critical",      "testKind": "behavior",      "priority": null,      "status": "flaky",      "durationMs": 4105,      "errorMessage": "Timed out 5000ms waiting for expect(locator).toHaveText(\"$45.00\")",      "files": [        "case.md",        "spec.ts"      ],      "attempts": [        {          "number": 1,          "retry": null,          "status": "failed",          "durationMs": 30412,          "startedAt": "2026-10-14T09:40:12.000Z",          "errorMessage": "Timed out 5000ms waiting for expect(locator).toHaveText(\"$45.00\")",          "errorStack": "Error: Timed out 5000ms waiting for expect(locator).toHaveText(\"$45.00\")\n    at checkout.spec.ts:24:41",          "files": [            "video.webm",            "trace.zip",            "screenshot-1.png"          ]        },        {          "number": 2,          "retry": 1,          "status": "passed",          "durationMs": 4210,          "startedAt": "2026-10-14T09:44:07.000Z",          "errorMessage": null,          "errorStack": null,          "files": []        },        {          "number": 3,          "retry": 1,          "status": "passed",          "durationMs": 4105,          "startedAt": "2026-10-14T09:44:13.000Z",          "errorMessage": null,          "errorStack": null,          "files": []        }      ]    },    {      "caseId": "docs-search-finds-guides",      "title": "docs › search finds guides",      "file": "docs.spec.ts",      "coverage": "acceptance",      "testKind": "journey",      "priority": null,      "status": "passed",      "durationMs": 6820,      "errorMessage": null,      "files": [        "case.md",        "spec.ts"      ],      "attempts": [        {          "number": 1,          "retry": null,          "status": "passed",          "durationMs": 6820,          "startedAt": "2026-10-14T09:40:12.000Z",          "errorMessage": null,          "errorStack": null,          "files": []        }      ]    }  ]}

Finish a test run

POST/v1/workspaces/{slug}/test-runs/{run}/finish

Records every test with its first attempt, counts the tests and closes the run as finished, or interrupted when interrupted is true. Only the run's publisher can finish it, and only while it is running. A finished run with no tests gets the error No tests ran. and fails.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

runintegerRequired

The run's number in the workspace, such as 1289.

Body parameters

interruptedbooleanRequired

Whether the run stopped early, such as on Ctrl-C. An interrupted run keeps its tests but gets no result.

errornullable string

What Playwright reported outside the tests, such as a web server that did not start. It fails the run. Ignored when interrupted is true.

durationMsnumberRequired

How long the run took, in milliseconds.

cleanupnullable object

What deleting the run's scope reported. Required for a run with a scope; a scope with no report counts as incomplete.

testsarray of objectsRequired

Every test the run ran, up to 5,000, each with a unique caseId.

Returns

Returns an object with these fields. Status 200.

A test run without its retries and tests: what it tested, its state, result and counts.

idstringRequired

Unique ID of the test run.

numbernumberRequired

The run's number, counting up from 1 in each workspace, such as 1289.

urlstringRequired

The run's page on the website.

statestringRequired

running until its publisher finishes it as finished or interrupted. One still running after 6 hours becomes interrupted.

One ofrunningfinishedinterrupted

resultnullable stringRequired

passed when the run has no error and no failed test, otherwise failed. Flaky tests count as passed. Null while running and for interrupted runs.

One ofpassedfailed

countsobjectRequired

How many tests have each status.

passRatenullable numberRequired

(passed + flaky) ÷ (tests − skipped), from 0 to 1. Null while running or when no test counts.

firstAttemptPassRatenullable numberRequired

Tests that passed on attempt 1 ÷ (tests − skipped), from 0 to 1. Retries never change it. Null while running or when no test counts.

errornullable stringRequired

What failed outside the tests, such as a web server that did not start, or No tests ran. A run with an error is failed and cannot be retried.

productobjectRequired

The product the run tested.

environmentobjectRequired

The environment the run tested.

baseUrlstringRequired

The URL the tests ran against.

deploymentBaseUrlnullable stringRequired

The deployment's URL when the run started, or null. It differs from baseUrl when clanker run --base-url overrode it.

deploymentVersionnullable stringRequired

The deployment's version when the run started, or null.

gitobjectRequired

The commit the run tested.

machineobjectRequired

The computer that ran the tests.

coveragenullable stringRequired

The coverage level the run selected, or null when it selected none.

One ofcriticalacceptanceregressionexhaustive

cleanupnullable objectRequired

The run's scope and what deleting it reported, or null when the deployment had no Fixture API.

publishedByobjectRequired

Who published a run or a retry: a person, an account API key, or one since removed.

startedAtstringRequired

When the run started, as an ISO 8601 timestamp.

finishedAtnullable stringRequired

When the run finished or was marked interrupted, as an ISO 8601 timestamp, or null while running.

durationMsnumberRequired

How long the run took, in milliseconds, as its publisher reported. 0 while running.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

POST/v1/workspaces/{slug}/test-runs/{run}/finish

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/test-runs/{run}/finish \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "interrupted": false,6    "error": null,7    "durationMs": 151230,8    "cleanup": {9      "status": "complete",10      "deleted": 214,11      "remaining": 0,12      "error": null13    },14    "tests": [15      {16        "caseId": "checkout-applies-coupon",17        "title": "checkout › applies a coupon",18        "file": "checkout.spec.ts",19        "coverage": "critical",20        "testKind": "behavior",21        "priority": null,22        "files": [23          "case.md",24          "spec.ts"25        ],26        "attempt": {27          "status": "failed",28          "durationMs": 30412,29          "startedAt": "2026-10-14T09:40:12.000Z",30          "errorMessage": "Timed out 5000ms waiting for expect(locator).toHaveText(\"$45.00\")",31          "errorStack": "Error: Timed out 5000ms waiting for expect(locator).toHaveText(\"$45.00\")\n    at checkout.spec.ts:24:41",32          "files": [33            "video.webm",34            "trace.zip",35            "screenshot-1.png"36          ]37        }38      },39      {40        "caseId": "docs-search-finds-guides",41        "title": "docs › search finds guides",42        "file": "docs.spec.ts",43        "coverage": "acceptance",44        "testKind": "journey",45        "priority": null,46        "files": [47          "case.md",48          "spec.ts"49        ],50        "attempt": {51          "status": "passed",52          "durationMs": 6820,53          "startedAt": "2026-10-14T09:40:12.000Z",54          "errorMessage": null,55          "errorStack": null,56          "files": []57        }58      }59    ]60  }'

Response200

{  "id": "Tr8KcW3nPx5Q",  "number": 1289,  "url": "https://clankertest.com/w/acme/test-runs/1289",  "state": "finished",  "result": "passed",  "counts": {    "total": 2,    "passed": 1,    "flaky": 1,    "failed": 0,    "skipped": 0  },  "passRate": 1,  "firstAttemptPassRate": 0.5,  "error": null,  "product": {    "slug": "storefront",    "name": "Storefront"  },  "environment": {    "slug": "staging",    "name": "Staging",    "class": "non-production"  },  "baseUrl": "https://staging.acme.dev",  "deploymentBaseUrl": "https://staging.acme.dev",  "deploymentVersion": "9f2c41e",  "git": {    "branch": "web-31-docs-search",    "sha": "9f2c41e7b8a3d5c6f1e0b2a4d6c8e0f1a3b5c7d9",    "dirty": false,    "subject": "Add docs search"  },  "machine": {    "hostname": "maya-mbp",    "platform": "darwin"  },  "coverage": null,  "cleanup": {    "scope": "scp_7h2k9q2m4x1a",    "expiresAt": "2026-10-14T15:40:00.000Z",    "status": "complete",    "deleted": 214,    "remaining": 0  },  "publishedBy": {    "kind": "user",    "name": "Maya Patel",    "email": "maya@acme.dev"  },  "startedAt": "2026-10-14T09:40:00.000Z",  "finishedAt": "2026-10-14T09:42:31.000Z",  "durationMs": 151230}

Start a retry

POST/v1/workspaces/{slug}/test-runs/{run}/retries

Starts a retry of a finished run's failed tests and returns them with the URL to test. The run must have no error, git.sha must match its commit and only one retry runs at a time, or the request fails with Conflict; viewers cannot retry runs. Its publisher uploads the retry's files like the run's, then finishes the retry.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

runintegerRequired

The run's number in the workspace, such as 1289.

Body parameters

passesnumberRequired

How many passing attempts a failed test needs to count as flaky, 1 to 5.

baseUrlnullable stringRequired

The URL to test instead of the run's, or null for the run's.

fixtureUrlnullable string

Use this Fixture API instead of the deployment's, such as a local server on another port. The fixture token is only valid there.

gitobjectRequired

The commit being tested. sha must be the commit the run tested.

machineobjectRequired

The computer running the tests.

Returns

Returns an object with these fields. Status 201.

retrynumberRequired

The retry's number within the run.

requiredPassesnumberRequired

How many passing attempts a failed test needs to count as flaky.

baseUrlstringRequired

The URL to test.

testsarray of objectsRequired

The run's failed tests, to run again.

environmentobjectRequired

The environment the run tested.

fixturenullable FixtureGrant objectRequired

A new scope and fixture token for the retry, or null when the run had no Fixture API.

semaphoresobjectRequired

Where a run or retry takes semaphore leases, and the run token it takes them with.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

POST/v1/workspaces/{slug}/test-runs/{run}/retries

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/test-runs/{run}/retries \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "passes": 2,6    "baseUrl": null,7    "git": {8      "branch": "web-31-docs-search",9      "sha": "9f2c41e7b8a3d5c6f1e0b2a4d6c8e0f1a3b5c7d9",10      "dirty": false,11      "subject": "Add docs search"12    },13    "machine": {14      "hostname": "maya-mbp",15      "platform": "darwin"16    }17  }'

Response201

{  "retry": 1,  "requiredPasses": 2,  "baseUrl": "https://staging.acme.dev",  "tests": [    {      "caseId": "checkout-applies-coupon",      "title": "checkout › applies a coupon",      "file": "checkout.spec.ts",      "nextAttempt": 2    }  ],  "environment": {    "slug": "staging",    "class": "non-production"  },  "fixture": {    "scope": "scp_7h2k9q2m4x1a",    "token": "eyJhbGciOiJFZERTQSIsImtpZCI6ImZ4XzEifQ.eyJzY29wZSI6InNjcF83aDJrOXEybTR4MWEifQ.c2lnbmF0dXJl",    "url": "https://staging.acme.dev/fixtures",    "expiresAt": "2026-10-14T15:40:00.000Z"  },  "semaphores": {    "url": "https://api.clankertest.com/v1/workspaces/Wk7Qm2RtXa9L/semaphores",    "token": "eyJhbGciOiJFZERTQSIsImtpZCI6ImZ4XzEifQ.eyJraW5kIjoicnVuIiwicnVuIjoxMjg5fQ.c2lnbmF0dXJl",    "expiresAt": "2026-10-14T15:40:00.000Z"  }}

Finish a retry

POST/v1/workspaces/{slug}/test-runs/{run}/retries/{retry}/finish

Adds the retry's attempts to the run and recounts it. A failed test that ran at least requiredPasses times and passed every time becomes flaky. Only the retry's publisher can finish it, and only while it is running.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

runintegerRequired

The run's number in the workspace, such as 1289.

retryintegerRequired

The retry's number within the run, such as 1.

Body parameters

interruptedbooleanRequired

Whether the retry stopped early. The attempts sent still count.

cleanupnullable object

What deleting the retry's scope reported. Required for a retry with a scope.

testsarray of objectsRequired

The tests this retry ran.

Returns

Returns an object with these fields. Status 200.

A test run without its retries and tests: what it tested, its state, result and counts.

idstringRequired

Unique ID of the test run.

numbernumberRequired

The run's number, counting up from 1 in each workspace, such as 1289.

urlstringRequired

The run's page on the website.

statestringRequired

running until its publisher finishes it as finished or interrupted. One still running after 6 hours becomes interrupted.

One ofrunningfinishedinterrupted

resultnullable stringRequired

passed when the run has no error and no failed test, otherwise failed. Flaky tests count as passed. Null while running and for interrupted runs.

One ofpassedfailed

countsobjectRequired

How many tests have each status.

passRatenullable numberRequired

(passed + flaky) ÷ (tests − skipped), from 0 to 1. Null while running or when no test counts.

firstAttemptPassRatenullable numberRequired

Tests that passed on attempt 1 ÷ (tests − skipped), from 0 to 1. Retries never change it. Null while running or when no test counts.

errornullable stringRequired

What failed outside the tests, such as a web server that did not start, or No tests ran. A run with an error is failed and cannot be retried.

productobjectRequired

The product the run tested.

environmentobjectRequired

The environment the run tested.

baseUrlstringRequired

The URL the tests ran against.

deploymentBaseUrlnullable stringRequired

The deployment's URL when the run started, or null. It differs from baseUrl when clanker run --base-url overrode it.

deploymentVersionnullable stringRequired

The deployment's version when the run started, or null.

gitobjectRequired

The commit the run tested.

machineobjectRequired

The computer that ran the tests.

coveragenullable stringRequired

The coverage level the run selected, or null when it selected none.

One ofcriticalacceptanceregressionexhaustive

cleanupnullable objectRequired

The run's scope and what deleting it reported, or null when the deployment had no Fixture API.

publishedByobjectRequired

Who published a run or a retry: a person, an account API key, or one since removed.

startedAtstringRequired

When the run started, as an ISO 8601 timestamp.

finishedAtnullable stringRequired

When the run finished or was marked interrupted, as an ISO 8601 timestamp, or null while running.

durationMsnumberRequired

How long the run took, in milliseconds, as its publisher reported. 0 while running.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

POST/v1/workspaces/{slug}/test-runs/{run}/retries/{retry}/finish

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/test-runs/{run}/retries/{retry}/finish \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "interrupted": false,6    "cleanup": {7      "status": "complete",8      "deleted": 12,9      "remaining": 0,10      "error": null11    },12    "tests": [13      {14        "caseId": "checkout-applies-coupon",15        "attempts": [16          {17            "status": "passed",18            "durationMs": 4210,19            "startedAt": "2026-10-14T09:44:07.000Z",20            "errorMessage": null,21            "errorStack": null,22            "files": []23          },24          {25            "status": "passed",26            "durationMs": 4105,27            "startedAt": "2026-10-14T09:44:13.000Z",28            "errorMessage": null,29            "errorStack": null,30            "files": []31          }32        ]33      }34    ]35  }'

Response200

{  "id": "Tr8KcW3nPx5Q",  "number": 1289,  "url": "https://clankertest.com/w/acme/test-runs/1289",  "state": "finished",  "result": "passed",  "counts": {    "total": 2,    "passed": 1,    "flaky": 1,    "failed": 0,    "skipped": 0  },  "passRate": 1,  "firstAttemptPassRate": 0.5,  "error": null,  "product": {    "slug": "storefront",    "name": "Storefront"  },  "environment": {    "slug": "staging",    "name": "Staging",    "class": "non-production"  },  "baseUrl": "https://staging.acme.dev",  "deploymentBaseUrl": "https://staging.acme.dev",  "deploymentVersion": "9f2c41e",  "git": {    "branch": "web-31-docs-search",    "sha": "9f2c41e7b8a3d5c6f1e0b2a4d6c8e0f1a3b5c7d9",    "dirty": false,    "subject": "Add docs search"  },  "machine": {    "hostname": "maya-mbp",    "platform": "darwin"  },  "coverage": null,  "cleanup": {    "scope": "scp_7h2k9q2m4x1a",    "expiresAt": "2026-10-14T15:40:00.000Z",    "status": "complete",    "deleted": 214,    "remaining": 0  },  "publishedBy": {    "kind": "user",    "name": "Maya Patel",    "email": "maya@acme.dev"  },  "startedAt": "2026-10-14T09:40:00.000Z",  "finishedAt": "2026-10-14T09:42:31.000Z",  "durationMs": 151230}

NextSemaphores