# Runs

Query and manage test runs.

A run represents a single execution of your test suite. Runs contain spec files which are executed across multiple instances. You can query run details, cancel runs, reset failed specs, and delete runs.

Per-test outcome counters on specs (`results.stats`) use the `RecordedTestOutcome` vocabulary—see **components/schemas** for how **pending** and **skipped** differ from **failures**.

## Get run

> Get a single run by ID with full details. Runs with many test files can produce a large JSON response. Include \`Accept-Encoding: gzip\` in your request when possible. Spec \`results.stats\` exposes \*\*pending\*\*, \*\*skipped\*\*, and \*\*failures\*\* separately; see \`RecordedTestOutcome\` in components/schemas and compare to Tests Explorer \`metrics\` mapping. For narrative context, see the \[Test result statuses]\(<https://docs.currents.dev/dashboard/test-suite-performance-explorer/tests-explorer#test-result-statuses>) section on the Test Explorer documentation page.

```json
{"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Query and manage test runs.\n\nA run represents a single execution of your test suite. Runs contain spec files\nwhich are executed across multiple instances. You can query run details, cancel\nruns, reset failed specs, and delete runs.\n\nPer-test outcome counters on specs (`results.stats`) use the `RecordedTestOutcome` vocabulary—see **components/schemas** for how **pending** and **skipped** differ from **failures**."}],"servers":[{"url":"https://api.currents.dev/v1","description":"Production API"},{"url":"https://api-staging.currents.dev/v1","description":"Staging API"},{"url":"http://localhost:4000/v1","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication using Bearer token"}},"parameters":{"RunIdPath":{"name":"runId","in":"path","required":true,"description":"The run ID","schema":{"type":"string"}}},"schemas":{"RunResponse":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"$ref":"#/components/schemas/Run"}}},"Run":{"type":"object","required":["runId","projectId","createdAt","completionState","status"],"properties":{"runId":{"type":"string","description":"Unique identifier for the run"},"projectId":{"type":"string","description":"Project this run belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When the run was created"},"durationMs":{"type":"integer","nullable":true,"description":"Total duration of the run in milliseconds"},"deletedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the run was deleted"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags associated with this run"},"previousRunId":{"type":"string","nullable":true,"description":"ID of the previous run (for retry runs)"},"timeout":{"type":"object","properties":{"isTimeout":{"type":"boolean"},"timeoutValueMs":{"type":"integer","nullable":true}}},"cancellation":{"type":"object","nullable":true,"properties":{"cancelledAt":{"type":"string","format":"date-time"},"cancelledBy":{"type":"string"},"reason":{"type":"string"}}},"groups":{"type":"array","items":{"$ref":"#/components/schemas/RunGroup"}},"meta":{"$ref":"#/components/schemas/RunMeta"},"specs":{"type":"array","items":{"$ref":"#/components/schemas/RunSpec"}},"completionState":{"type":"string","enum":["complete","incomplete","cancelled","timedOut"],"description":"The completion state of the run"},"status":{"type":"string","enum":["passed","failed","running","cancelled","timedOut"],"description":"The overall status of the run"}}},"RunGroup":{"type":"object","properties":{"groupId":{"type":"string"},"platform":{"type":"object","properties":{"osName":{"type":"string"},"osVersion":{"type":"string"},"browserName":{"type":"string"},"browserVersion":{"type":"string"}}},"tests":{"type":"object","description":"Rollup test counts for this group (`RecordedTestOutcome` semantics; see components/schemas).","properties":{"overall":{"type":"integer"},"passes":{"type":"integer"},"failures":{"type":"integer"},"pending":{"type":"integer","description":"**pending** outcomes (intentional skips)."},"skipped":{"type":"integer","description":"**skipped** outcomes (separate from `failures` here; see schema for Tests Explorer difference)."},"flaky":{"type":"integer"}}}}},"RunMeta":{"type":"object","properties":{"ciBuildId":{"type":"string","description":"CI build identifier"},"pr":{"type":"object","nullable":true,"description":"Normalized pull request metadata when the run is associated with a PR","properties":{"id":{"type":"string","nullable":true},"link":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"source":{"type":"string","nullable":true},"destination":{"type":"string","nullable":true}}},"commit":{"type":"object","properties":{"sha":{"type":"string"},"branch":{"type":"string"},"authorName":{"type":"string"},"authorEmail":{"type":"string"},"message":{"type":"string"},"remoteOrigin":{"type":"string"}}},"framework":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"}}}}},"RunSpec":{"type":"object","properties":{"spec":{"type":"string","description":"Spec file path"},"groupId":{"type":"string"},"instanceId":{"type":"string"},"claimedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"machineId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags associated with this spec (Playwright only)"},"inactivityTimeoutMs":{"type":"integer","nullable":true,"description":"Inactivity timeout in milliseconds"},"results":{"type":"object","nullable":true,"properties":{"stats":{"type":"object","description":"Totals for completed tests in this spec. Counters follow `RecordedTestOutcome` (see components/schemas): `pending` and `skipped` are each separate from `failures`.","properties":{"suites":{"type":"integer"},"tests":{"type":"integer"},"passes":{"type":"integer","description":"Count of **passed** outcomes (test passed)"},"failures":{"type":"integer","description":"Count of **failed** outcomes (test failed)"},"pending":{"type":"integer","description":"Count of **pending** outcomes (intentional skips it.skip())"},"skipped":{"type":"integer","description":"Count of **skipped** outcomes - test was supposed to run but was interrupted"},"flaky":{"type":"integer"},"overall":{"type":"integer","description":"Deprecated: use tests instead. Total number of tests (Playwright only)","deprecated":true},"wallClockStartedAt":{"type":"string","format":"date-time"},"wallClockEndedAt":{"type":"string","format":"date-time"},"wallClockDuration":{"type":"integer","description":"Duration in milliseconds"},"startedAt":{"type":"string","format":"date-time","description":"Alias for wallClockStartedAt"},"endedAt":{"type":"string","format":"date-time","description":"Alias for wallClockEndedAt"},"duration":{"type":"integer","description":"Alias for wallClockDuration in milliseconds"}}},"exception":{"type":"string","nullable":true},"flaky":{"type":"integer"},"videoUrl":{"type":"string","nullable":true,"description":"Signed URL to the video recording (Cypress only, null for Playwright)"},"screenshots":{"type":"array","description":"Screenshots captured during test execution (Cypress only)","items":{"type":"object","properties":{"screenshotId":{"type":"string"},"name":{"type":"string","nullable":true},"testId":{"type":"string"},"testAttemptIndex":{"type":"integer"},"takenAt":{"type":"string","format":"date-time"},"screenshotURL":{"type":"string","description":"Signed URL to the screenshot"}}}}}}}},"ErrorResponse":{"type":"object","required":["status","error"],"properties":{"status":{"type":"string","enum":["FAILED"]},"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/runs/{runId}":{"get":{"summary":"Get run","description":"Get a single run by ID with full details. Runs with many test files can produce a large JSON response. Include `Accept-Encoding: gzip` in your request when possible. Spec `results.stats` exposes **pending**, **skipped**, and **failures** separately; see `RecordedTestOutcome` in components/schemas and compare to Tests Explorer `metrics` mapping. For narrative context, see the [Test result statuses](https://docs.currents.dev/dashboard/test-suite-performance-explorer/tests-explorer#test-result-statuses) section on the Test Explorer documentation page.","operationId":"getRun","tags":["Runs"],"parameters":[{"$ref":"#/components/parameters/RunIdPath"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"description":"Payload Too Large - Response size exceeds limits. Use Accept-Encoding: gzip header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Delete run

> Delete a run and all associated data

```json
{"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Query and manage test runs.\n\nA run represents a single execution of your test suite. Runs contain spec files\nwhich are executed across multiple instances. You can query run details, cancel\nruns, reset failed specs, and delete runs.\n\nPer-test outcome counters on specs (`results.stats`) use the `RecordedTestOutcome` vocabulary—see **components/schemas** for how **pending** and **skipped** differ from **failures**."}],"servers":[{"url":"https://api.currents.dev/v1","description":"Production API"},{"url":"https://api-staging.currents.dev/v1","description":"Staging API"},{"url":"http://localhost:4000/v1","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication using Bearer token"}},"parameters":{"RunIdPath":{"name":"runId","in":"path","required":true,"description":"The run ID","schema":{"type":"string"}}},"schemas":{"RunDeleteResponse":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"type":"object","properties":{"runId":{"type":"string"}}}}},"ErrorResponse":{"type":"object","required":["status","error"],"properties":{"status":{"type":"string","enum":["FAILED"]},"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/runs/{runId}":{"delete":{"summary":"Delete run","description":"Delete a run and all associated data","operationId":"deleteRun","tags":["Runs"],"parameters":[{"$ref":"#/components/parameters/RunIdPath"}],"responses":{"200":{"description":"Run deleted successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunDeleteResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Find run

> Find a run by query parameters. Returns the most recent completed run matching the criteria. For runs with many test files, the response can be large. There is a 1MB response limit. It is strongly recommended to include \`Accept-Encoding: gzip\` header in your request to enable compression.

```json
{"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Query and manage test runs.\n\nA run represents a single execution of your test suite. Runs contain spec files\nwhich are executed across multiple instances. You can query run details, cancel\nruns, reset failed specs, and delete runs.\n\nPer-test outcome counters on specs (`results.stats`) use the `RecordedTestOutcome` vocabulary—see **components/schemas** for how **pending** and **skipped** differ from **failures**."}],"servers":[{"url":"https://api.currents.dev/v1","description":"Production API"},{"url":"https://api-staging.currents.dev/v1","description":"Staging API"},{"url":"http://localhost:4000/v1","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication using Bearer token"}},"parameters":{"ProjectIdQuery":{"name":"projectId","in":"query","required":true,"description":"The project ID","schema":{"type":"string"}},"TagsQuery":{"name":"tags[]","in":"query","required":false,"description":"Filter by tags (can be specified multiple times using bracket notation, e.g., tags[]=value1&tags[]=value2)","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true}},"schemas":{"BranchFilterQueryValue":{"description":"Branch filter value: an exact branch name, or a trailing `*` for prefix match (e.g. `release/*`). Max 250 characters.","oneOf":[{"type":"string","description":"Exact branch name (must not contain `*` or spaces).","pattern":"^[!-)+-~]+$","maxLength":250},{"type":"string","description":"Prefix match: branch prefix followed by `*`.","pattern":"^[!-)+-~]+\\*$","maxLength":250}]},"RunResponse":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"$ref":"#/components/schemas/Run"}}},"Run":{"type":"object","required":["runId","projectId","createdAt","completionState","status"],"properties":{"runId":{"type":"string","description":"Unique identifier for the run"},"projectId":{"type":"string","description":"Project this run belongs to"},"createdAt":{"type":"string","format":"date-time","description":"When the run was created"},"durationMs":{"type":"integer","nullable":true,"description":"Total duration of the run in milliseconds"},"deletedAt":{"type":"string","format":"date-time","nullable":true,"description":"When the run was deleted"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags associated with this run"},"previousRunId":{"type":"string","nullable":true,"description":"ID of the previous run (for retry runs)"},"timeout":{"type":"object","properties":{"isTimeout":{"type":"boolean"},"timeoutValueMs":{"type":"integer","nullable":true}}},"cancellation":{"type":"object","nullable":true,"properties":{"cancelledAt":{"type":"string","format":"date-time"},"cancelledBy":{"type":"string"},"reason":{"type":"string"}}},"groups":{"type":"array","items":{"$ref":"#/components/schemas/RunGroup"}},"meta":{"$ref":"#/components/schemas/RunMeta"},"specs":{"type":"array","items":{"$ref":"#/components/schemas/RunSpec"}},"completionState":{"type":"string","enum":["complete","incomplete","cancelled","timedOut"],"description":"The completion state of the run"},"status":{"type":"string","enum":["passed","failed","running","cancelled","timedOut"],"description":"The overall status of the run"}}},"RunGroup":{"type":"object","properties":{"groupId":{"type":"string"},"platform":{"type":"object","properties":{"osName":{"type":"string"},"osVersion":{"type":"string"},"browserName":{"type":"string"},"browserVersion":{"type":"string"}}},"tests":{"type":"object","description":"Rollup test counts for this group (`RecordedTestOutcome` semantics; see components/schemas).","properties":{"overall":{"type":"integer"},"passes":{"type":"integer"},"failures":{"type":"integer"},"pending":{"type":"integer","description":"**pending** outcomes (intentional skips)."},"skipped":{"type":"integer","description":"**skipped** outcomes (separate from `failures` here; see schema for Tests Explorer difference)."},"flaky":{"type":"integer"}}}}},"RunMeta":{"type":"object","properties":{"ciBuildId":{"type":"string","description":"CI build identifier"},"pr":{"type":"object","nullable":true,"description":"Normalized pull request metadata when the run is associated with a PR","properties":{"id":{"type":"string","nullable":true},"link":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"source":{"type":"string","nullable":true},"destination":{"type":"string","nullable":true}}},"commit":{"type":"object","properties":{"sha":{"type":"string"},"branch":{"type":"string"},"authorName":{"type":"string"},"authorEmail":{"type":"string"},"message":{"type":"string"},"remoteOrigin":{"type":"string"}}},"framework":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"}}}}},"RunSpec":{"type":"object","properties":{"spec":{"type":"string","description":"Spec file path"},"groupId":{"type":"string"},"instanceId":{"type":"string"},"claimedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time","nullable":true},"machineId":{"type":"string"},"tags":{"type":"array","items":{"type":"string"},"description":"Tags associated with this spec (Playwright only)"},"inactivityTimeoutMs":{"type":"integer","nullable":true,"description":"Inactivity timeout in milliseconds"},"results":{"type":"object","nullable":true,"properties":{"stats":{"type":"object","description":"Totals for completed tests in this spec. Counters follow `RecordedTestOutcome` (see components/schemas): `pending` and `skipped` are each separate from `failures`.","properties":{"suites":{"type":"integer"},"tests":{"type":"integer"},"passes":{"type":"integer","description":"Count of **passed** outcomes (test passed)"},"failures":{"type":"integer","description":"Count of **failed** outcomes (test failed)"},"pending":{"type":"integer","description":"Count of **pending** outcomes (intentional skips it.skip())"},"skipped":{"type":"integer","description":"Count of **skipped** outcomes - test was supposed to run but was interrupted"},"flaky":{"type":"integer"},"overall":{"type":"integer","description":"Deprecated: use tests instead. Total number of tests (Playwright only)","deprecated":true},"wallClockStartedAt":{"type":"string","format":"date-time"},"wallClockEndedAt":{"type":"string","format":"date-time"},"wallClockDuration":{"type":"integer","description":"Duration in milliseconds"},"startedAt":{"type":"string","format":"date-time","description":"Alias for wallClockStartedAt"},"endedAt":{"type":"string","format":"date-time","description":"Alias for wallClockEndedAt"},"duration":{"type":"integer","description":"Alias for wallClockDuration in milliseconds"}}},"exception":{"type":"string","nullable":true},"flaky":{"type":"integer"},"videoUrl":{"type":"string","nullable":true,"description":"Signed URL to the video recording (Cypress only, null for Playwright)"},"screenshots":{"type":"array","description":"Screenshots captured during test execution (Cypress only)","items":{"type":"object","properties":{"screenshotId":{"type":"string"},"name":{"type":"string","nullable":true},"testId":{"type":"string"},"testAttemptIndex":{"type":"integer"},"takenAt":{"type":"string","format":"date-time"},"screenshotURL":{"type":"string","description":"Signed URL to the screenshot"}}}}}}}},"ErrorResponse":{"type":"object","required":["status","error"],"properties":{"status":{"type":"string","enum":["FAILED"]},"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/runs/find":{"get":{"summary":"Find run","description":"Find a run by query parameters. Returns the most recent completed run matching the criteria. For runs with many test files, the response can be large. There is a 1MB response limit. It is strongly recommended to include `Accept-Encoding: gzip` header in your request to enable compression.","operationId":"findRun","tags":["Runs"],"parameters":[{"$ref":"#/components/parameters/ProjectIdQuery"},{"name":"ciBuildId","in":"query","required":false,"description":"The CI build ID. If provided, returns the run with this exact ciBuildId.","schema":{"type":"string"}},{"name":"branch","in":"query","required":false,"description":"Git branch name. Used when ciBuildId is not provided. Supports a trailing `*` for prefix search (e.g., `release/*`). `*` must not appear except as the final character. Each branch value is limited to 250 characters total (exact name or wildcard pattern).","schema":{"$ref":"#/components/schemas/BranchFilterQueryValue"}},{"$ref":"#/components/parameters/TagsQuery"},{"name":"tag[]","in":"query","required":false,"deprecated":true,"description":"Deprecated. Use tags[] instead. Run tags to filter by (can be specified multiple times using bracket notation, e.g., tag[]=tag1&tag[]=tag2)","schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true},{"name":"pwLastRun","in":"query","required":false,"description":"If true, includes information about failed tests from the last run (Playwright only)","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"413":{"description":"Payload Too Large - Response size exceeds limits. Use Accept-Encoding: gzip header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Cancel run

> Cancel a run in progress

```json
{"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Query and manage test runs.\n\nA run represents a single execution of your test suite. Runs contain spec files\nwhich are executed across multiple instances. You can query run details, cancel\nruns, reset failed specs, and delete runs.\n\nPer-test outcome counters on specs (`results.stats`) use the `RecordedTestOutcome` vocabulary—see **components/schemas** for how **pending** and **skipped** differ from **failures**."}],"servers":[{"url":"https://api.currents.dev/v1","description":"Production API"},{"url":"https://api-staging.currents.dev/v1","description":"Staging API"},{"url":"http://localhost:4000/v1","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication using Bearer token"}},"parameters":{"RunIdPath":{"name":"runId","in":"path","required":true,"description":"The run ID","schema":{"type":"string"}}},"schemas":{"RunCancellationResponse":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"type":"object","properties":{"runId":{"type":"string"},"cancelled":{"type":"boolean"},"cancelledAt":{"type":"string","format":"date-time"}}}}},"ErrorResponse":{"type":"object","required":["status","error"],"properties":{"status":{"type":"string","enum":["FAILED"]},"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/runs/{runId}/cancel":{"put":{"summary":"Cancel run","description":"Cancel a run in progress","operationId":"cancelRun","tags":["Runs"],"parameters":[{"$ref":"#/components/parameters/RunIdPath"}],"responses":{"200":{"description":"Run cancelled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunCancellationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Reset run

> Reset failed spec files in a run to allow re-execution. Requires specifying machineId(s) to reset.

```json
{"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Query and manage test runs.\n\nA run represents a single execution of your test suite. Runs contain spec files\nwhich are executed across multiple instances. You can query run details, cancel\nruns, reset failed specs, and delete runs.\n\nPer-test outcome counters on specs (`results.stats`) use the `RecordedTestOutcome` vocabulary—see **components/schemas** for how **pending** and **skipped** differ from **failures**."}],"servers":[{"url":"https://api.currents.dev/v1","description":"Production API"},{"url":"https://api-staging.currents.dev/v1","description":"Staging API"},{"url":"http://localhost:4000/v1","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication using Bearer token"}},"parameters":{"RunIdPath":{"name":"runId","in":"path","required":true,"description":"The run ID","schema":{"type":"string"}}},"schemas":{"ResetRunRequest":{"type":"object","required":["machineId"],"properties":{"machineId":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":63,"description":"Machine ID(s) to reset"},"isBatchedOr8n":{"type":"boolean","description":"Whether to use batched orchestration"}}},"ResetRunResponse":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"type":"object","description":"Reset operation result"}}},"ErrorResponse":{"type":"object","required":["status","error"],"properties":{"status":{"type":"string","enum":["FAILED"]},"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/runs/{runId}/reset":{"put":{"summary":"Reset run","description":"Reset failed spec files in a run to allow re-execution. Requires specifying machineId(s) to reset.","operationId":"resetRun","tags":["Runs"],"parameters":[{"$ref":"#/components/parameters/RunIdPath"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetRunRequest"}}}},"responses":{"200":{"description":"Run reset successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResetRunResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```

## Cancel run by GitHub CI

> Cancel a run by GitHub Actions workflow run ID and attempt number

```json
{"openapi":"3.0.2","info":{"title":"Currents REST API","version":"1.0.0"},"tags":[{"name":"Runs","description":"Query and manage test runs.\n\nA run represents a single execution of your test suite. Runs contain spec files\nwhich are executed across multiple instances. You can query run details, cancel\nruns, reset failed specs, and delete runs.\n\nPer-test outcome counters on specs (`results.stats`) use the `RecordedTestOutcome` vocabulary—see **components/schemas** for how **pending** and **skipped** differ from **failures**."}],"servers":[{"url":"https://api.currents.dev/v1","description":"Production API"},{"url":"https://api-staging.currents.dev/v1","description":"Staging API"},{"url":"http://localhost:4000/v1","description":"Local development"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication using Bearer token"}},"schemas":{"CancelRunGithubCIRequest":{"type":"object","required":["githubRunId","githubRunAttempt"],"properties":{"githubRunId":{"type":"string","description":"GitHub Actions workflow run ID"},"githubRunAttempt":{"type":"integer","description":"GitHub Actions workflow run attempt number"},"projectId":{"type":"string","description":"Optional project ID to scope the cancellation"},"ciBuildId":{"type":"string","description":"Optional CI build ID to scope the cancellation"}}},"RunCancellationResponse":{"type":"object","required":["status","data"],"properties":{"status":{"type":"string","enum":["OK"]},"data":{"type":"object","properties":{"runId":{"type":"string"},"cancelled":{"type":"boolean"},"cancelledAt":{"type":"string","format":"date-time"}}}}},"ErrorResponse":{"type":"object","required":["status","error"],"properties":{"status":{"type":"string","enum":["FAILED"]},"error":{"type":"string","description":"Error message"}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Unauthorized":{"description":"Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/runs/cancel-ci/github":{"put":{"summary":"Cancel run by GitHub CI","description":"Cancel a run by GitHub Actions workflow run ID and attempt number","operationId":"cancelRunByGithubCI","tags":["Runs"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CancelRunGithubCIRequest"}}}},"responses":{"200":{"description":"Run cancelled successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunCancellationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.currents.dev/api/resources/runs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.