---
title: "Start an authored Test asynchronously"
method: POST
path: "/api/v2/projects/{projectId}/tests/{testId}/runs"
tags: ["Tests"]
---

# Start an authored Test asynchronously

`POST /api/v2/projects/{projectId}/tests/{testId}/runs`

## Request

- Base URL: `https://davinci-app.com`
- URL: `https://davinci-app.com/api/v2/projects/{projectId}/tests/{testId}/runs`
- Auth: HTTP bearer

Validates a runnable leaf Test and starts its Results Value expression.
When that expression calls a Code object, the Code runs with the ordinary
`purpose=automation` execution grant it would have received from any
other caller. The route returns after scheduling; poll the run resource
for evidence, observation, native verdict, or infrastructure failure.

## Request body

- CreateTestRunRequest
  - `branch` string: Branch containing the authored Test. Defaults to `main`.

## Response `202`

Test run accepted.

- TestRun
  - `runId` string, uuid, required
  - `projectId` string, required
  - `branchName` string, required
  - `testId` string, required
  - `codeObjectId` string
  - `evaluationRunId` string, uuid
  - `status` 'queued' | 'starting' | 'running' | 'evaluating' | 'cancelling' | 'completed' | 'failed' | 'cancelled' | 'timed_out', required: `completed`, `failed`, `cancelled`, and `timed_out` are terminal. `failed` means the Code execution or evaluation infrastructure failed; a valid low observation still completes and may resolve to a failing Test verdict.
  - `observation` number: Finite numeric observation committed to the Test's Results Value.
  - `unit` string
  - `verdict` TestRunVerdict
    - `name` string, required
    - `score` number, nullable
    - `criteriaTarget` string
  - `evidence` object: Fixture-defined structured evidence. SYSTEM quality fixtures include transcript, final-tree, usage, and rubric summaries; callers must tolerate additional fixture-specific fields.
  - `failure` RunFailure
    - `code` 'EVALUATION_SCOPE_MISSING' | 'EVALUATION_AGENT_FAILED' | 'EVALUATION_TIMEOUT' | 'EVALUATION_EVIDENCE_MISSING' | 'EVALUATION_OBSERVATION_INVALID' | 'EVALUATION_CLEANUP_FAILED' | 'CODE_EXECUTION_FAILED' | 'TEST_CANCELLED' | 'TEST_RUN_FAILED' | 'TEST_RUN_TIMED_OUT', required
    - `message` string, required
    - `infrastructure` boolean, required: True when no quality verdict may be inferred from this failure.
    - `details` object
  - `createdAt` string, date-time, required
  - `startedAt` string, date-time
  - `completedAt` string, date-time
  - `updatedAt` string, date-time

## Other responses

- `400`: Malformed request parameters or body. Agile requests may return `INVALID_PAGINATION` or `INVALID_IDEMPOTENCY_KEY`.
- `401`: No credential was supplied, or the supplied credential is malformed, expired, or revoked. A credential that is present but unusable is never downgraded to an anonymous request.
- `403`: API key lacks a required scope. Error code is `INSUFFICIENT_SCOPES`.
- `404`: The resource does not exist in the parent named by the path, or is hidden from the caller. Absence and privacy denial are deliberately indistinguishable so project, organization, and private-team existence cannot be probed.
- `409`: The resource's current state no longer permits this operation, or a unique name, hierarchy, dependency, or lifecycle invariant would be violated. Examples include an active sprint that must be completed first, a duplicate card-tag name (`TAG_NAME_CONFLICT`), or a dependency cycle. Idempotent creates may return `IDEMPOTENCY_KEY_REUSED` or `IDEMPOTENCY_REQUEST_IN_PROGRESS`; the latter includes `Retry-After`.
- `422`: The request was understood, but required evaluation infrastructure or evidence was unavailable. Error codes include `EVALUATION_SCOPE_MISSING`, `EVALUATION_AGENT_FAILED`, `EVALUATION_TIMEOUT`, `EVALUATION_EVIDENCE_MISSING`, `EVALUATION_OBSERVATION_INVALID`, and `EVALUATION_CLEANUP_FAILED`. These conditions are never converted to a successful quality observation or a skipped Test.
- `429`: Request rate exceeded, either globally or for this key.
- `500`: Unexpected server error.

## Changes

- **2026-09-15** (v2) `67c8b8616dbb`: 8 info
  - the `success` response property const value `false` was added for the status `400`
  - the `success` response property const value `false` was added for the status `401`
  - the `success` response property const value `false` was added for the status `403`
  - the `success` response property const value `false` was added for the status `404`
  - …4 more
- **2026-09-15** (v2) `48948af37797`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/changes/api/v2/projects/:projectId/tests/:testId/runs/post.md)

---

[API](https://skmtc.dev/celedon-solutions/apis/davinci-public-api.md) - [All operations](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/celedon-solutions/apis/davinci-public-api/revisions/279218ca2e8d?raw)