Runlists

Trigger API Endpoints

External systems can trigger runlist runs and check their status through HTTP endpoints. These are publicly accessible and authenticated with the trigger secret, not user sessions.

Authentication

All trigger endpoints accept the secret via:

  • X-Trigger-Secret: <secret> header, or

  • Authorization: Bearer <secret> header

The secret is a SHA-256 hash stored in the trigger registration's config.secretHash. The raw secret is only returned once at creation time.

Trigger a Run

POST /triggers/:teamId/:teamDisplayId/:endpointSuffix

Triggers a runlist run. Returns:

JSON
{
  "status": "success",
  "runId": "fUkDtRvR",
  "triggerRunLogId": 12345,
  "ownerAssetType": "runlist",
  "ownerAssetId": 42,
  "ownerAssetName": "Smoke Tests"
}

Check Run Status

GET /triggers/:teamId/:teamDisplayId/:endpointSuffix/status?runId=<runId>

Returns run summary with overall status, timing, and per-test-case counts:

JSON
{
  "runId": "fUkDtRvR",
  "overallStatus": "succeeded",
  "startedAt": "2026-08-20T07:36:14.145Z",
  "completedAt": "2026-08-20T07:38:27.809Z",
  "durationMs": 133663,
  "passedCount": 8,
  "failedCount": 1,
  "queuedCount": 0,
  "stoppedCount": 0,
  "flakyCount": 0,
  "selectedTestCaseCount": 9
}

Check Run Status with Verbose Details

GET /triggers/:teamId/:teamDisplayId/:endpointSuffix/status?runId=<runId>&details=true

Same as above, plus a per-test-case breakdown. Every test case includes its final status, whether it recovered during execution, and the execution mode detected for that test case. Failed/stopped test cases additionally include errorSummary and failedSteps with step-level failure information:

JSON
{
  "runId": "fUkDtRvR",
  "overallStatus": "failed",
  "passedCount": 7,
  "failedCount": 2,
  "selectedTestCaseCount": 9,
  "testCases": [
    {
      "id": "zgdsIDyo",
      "name": "[C525566] Verify Auth Manager entries",
      "status": "failed",
      "isFlaky": false,
      "executionMode": "playwright",
      "errorSummary": "Playwright locator.click exceeded wall clock of 5s.",
      "failedSteps": [
        {
          "stepNumber": 3,
          "stepTitle": "Click Pay Button",
          "issueKind": "execution",
          "message": "Playwright locator.click exceeded wall clock of 5s."
        }
      ]
    },
    {
      "id": "aBcDeFg",
      "name": "Login flow",
      "status": "succeeded",
      "isFlaky": true,
      "executionMode": "self_heal"
    }
  ]
}

testCases fields:

Field

Description

id

Internal execution test-case identifier.

name

Test-case name at the time of the run.

status

Final test-case status, such as succeeded, failed, or stopped.

isFlaky

true when the test case recovered during execution and still completed successfully. Recovery can come from self-healing or XPath fallback. It is false when no such recovery was detected or when the final test-case status was not successful.

executionMode

Effective mode detected for the test case: playwright when no recovery was used, xpath when XPath fallback recovery was used, or self_heal when self-healing was used.

When more than one recovery mode is detected, executionMode uses this precedence: self_heal over xpath over playwright.

failedSteps fields:

Field

Description

stepNumber

1-based position of the failed step in the test case definition

stepTitle

Human-readable step title

issueKind

validation (assertion failure), self_heal (healed then failed), or execution (Playwright error)

message

Failure message describing what went wrong

CI/CD Polling Pattern

Bash
# 1. Trigger a run
RUN_ID=$(curl -s -X POST -H "x-trigger-secret: $SECRET" \
  "https://example.com/triggers/1/TM-1/my-suffix" | jq -r .runId)

# 2. Poll until terminal status
while true; do
  STATUS=$(curl -s -H "x-trigger-secret: $SECRET" \
    "https://example.com/triggers/1/TM-1/my-suffix/status?runId=$RUN_ID")
  CURRENT=$(echo $STATUS | jq -r .overallStatus)
  echo "Status: $CURRENT"
  case "$CURRENT" in
    succeeded) exit 0 ;;
    failed|stopped|partial) exit 1 ;;
    *) sleep 10 ;;
  esac
done

Error Responses

Status

Condition

400

Missing/invalid route params or runId query parameter

401

Missing or invalid trigger secret

403

Trigger secret not configured on the registration

404

Trigger not found, run not found, or run doesn't belong to the trigger's runlist/team