---
title: "Run a saved test session"
method: POST
path: "/v1/test-sessions/{sessionId}/run"
tags: ["Testing"]
---

# Run a saved test session

`POST /v1/test-sessions/{sessionId}/run`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/test-sessions/{sessionId}/run`
- Auth: HTTP bearer

Execute a saved PiperTest session via CDP. Supports maxDuration timeout (default 300s) and cooperative cancellation via the /run/cancel endpoint. Concurrent runs on the same session return 409 Conflict. Cancelled/timed-out steps report status "cancelled"/"timeout".

## Path parameters

- `sessionId` string, required

## Request body

- object
  - `healMode` string
  - `stopOnFailure` boolean
  - `screenshots` boolean
  - `coverage` boolean
  - `maxDuration` integer: Maximum run duration in seconds (default 300)

## Response `200`

Test run results (pass/fail per step, cancelledSteps count)

## Other responses

- `404`: Resource not found
- `409`: Run already in progress for this session

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)