Run a suite on a version

POST
/v1/tests/{id}/runs

Plays every case of the suite against one version of its agent, a draft or a published one, and judges each run with the reviews you expect. It is charged: each turn as a test and each review at its price, so quote.maxUsd is the most the whole suite can cost. Pass quoteOnly to get the price and run nothing. A case that cannot run is counted as refused with its reason, not as failed.

Requires an API key with the workspace:write scope.

Authorization

apiKey
headerAuthorizationBearer <token>

A secret API key from the dashboard (Developers → API keys): vl_live_…, or vl_test_… for test mode. Each operation says which scope the key needs.

Path Parameters

id*string

The suite id.

Request Body

application/json
  1. body
versionId?string

The version to run every case against: a published version of the suite’s agent. Give this or draft.

draft?boolean

Run on the agent’s current draft: it is sealed as a version first. Give this or versionId.

quoteOnly?boolean

Answer the price and run nothing.

quotedMaxUsd?number

The most the person saw and agreed to. A run whose ceiling is now higher is refused price_changed (409).

Response Body

The most the run can cost, and the suite run once it is queued

application/json
  1. response
quote*
suiteRun*|null
Example Request
curl -X POST "https://api.vlayers.ai/v1/tests/$SUITE_ID/runs" \  -H "Authorization: Bearer $VOICELAYER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "versionId": "0192f5b0-7c3e-7a51-9b2d-4e8f1a6c3d21",    "quoteOnly": true  }'
Example Response
{  "quote": {    "cases": 3,    "maxUsd": 1.2,    "typicalUsd": 0.3,    "maxTurns": 20,    "maxAttemptsPerRun": 2,    "analyzersMaxUsd": 0.1  },  "suiteRun": {    "id": "0192f5fa-e3f2-7d40-8f90-0123456789ab",    "suiteId": "0192f5f8-c1d0-7b2e-8d7e-8f9012345678",    "versionId": "0192f5d5-9cad-7ebf-9a4b-5c6d7e8f9012",    "status": "queued",    "quoteMaxUsd": 1.2,    "cases": 3,    "passed": 0,    "failed": 0,    "refused": 0,    "createdBy": "user_2abc",    "createdAt": "2026-10-20T15:04:05.000Z",    "finishedAt": null,    "expiresAt": "2026-10-20T15:04:05.000Z"  }}