---
search:
  tags:
    - V1
    - POST
seo:
  description: >-
    Runs the test suite's latest published version… Reference for the POST
    /v1/projects/{projectId}/test-suites/{testSuiteId}/runs endpoint in the
    Judgeval API.
sidebar:
  label: Start a test run
  badge: POST
title: Start a test run
type: openapi-operation
---
Runs the test suite's latest published version over the cases the filter selects; each case is scored by the checks in its expected. Run your agent once per returned case on your normal tracer, with judgment.test.run_id and judgment.test.case_id set; traces are attached and scored as they arrive.

`POST /v1/projects/{projectId}/test-suites/{testSuiteId}/runs`

**Request body** (`application/json`, required)

- `case_filter` (TestCaseFilter)
- `candidate` (string) — What is being tested, for example a git SHA or agent version.
- `candidate_meta` (object)
- `trigger` (string)

Request body example:

```json
{
  "case_filter": {
    "kind": "all"
  },
  "candidate": "string",
  "candidate_meta": {},
  "trigger": "manual"
}
```

**Responses**

- `200` — Response for status 200
- `404` — Response for status 404
- `409` — Response for status 409
- `422` — Response for status 422

Response example, 200:

```json
{
  "run_id": "dded282c-8ebd-44cf-8ba5-9a234973d1ec",
  "test_suite_version": 0,
  "cases": [
    {
      "case_id": "c74269e5-1f97-4e20-9164-ffbe3494d8d6",
      "input": null,
      "headers": {}
    }
  ]
}
```