API Reference

Runs API

Run execution and monitoring endpoints.

Overview

Runs execute validation against selected cases or suites. Monitor status, fetch logs, cancel in-flight runs, and download artifacts programmatically for CI gates and reporting pipelines.

Terminal statuses: passed, failed, error, canceled. Poll GET /runs/{id} or subscribe to run.completed webhook for completion.

Prerequisites

  • project_id from Console or projects API
  • Reviewed test case IDs or suite ID
  • Environment matching deployment target

Step-by-step procedure

Start run

POST /v1/runs with project_id, environment, case or suite IDs.

Send Idempotency-Key header in CI retries.

Wait for completion

Poll GET /v1/runs/{id} or use SDK waitUntilComplete.

Subscribe to run.completed webhook for event-driven flows.

Gate pipeline

Fail job on failed or error status.

Attach run URL to change ticket.

Start run

POST /v1/runs
{
  "project_id": "proj_abc123",
  "environment": "staging",
  "test_case_ids": ["tc_login_001", "tc_checkout_014"]
}

API operations

GET
/runs
List runs with filters (project, status, date)
POST
/runs
Start run with project_id, environment, case IDs
GET
/runs/{id}
Status, summary, case outcomes
POST
/runs/{id}/cancel
Cancel queued or running validation
GET
/runs/{id}/logs
Execution logs
GET
/runs/{id}/artifacts
Screenshots, traces, exports

Was this page helpful?