> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clickproof.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Run tests

> POST /api/v1/projects/{projectId}/runs

<div className="text-sm font-mono">POST /api/v1/projects/{`{projectId}`}/runs</div>

Run a project's tests against its current build. Omit the body to run **every**
test in the project (a suite); pass a `testId` to run just one. Returns the run
ids to poll.

<Note>
  Upload a build first — this returns `400 no build uploaded` if the project has
  none.
</Note>

## Request

<ParamField path="projectId" type="string" required>
  The project id, in the URL path.
</ParamField>

<ParamField header="Authorization" type="string" required>
  `Bearer <your API key>`.
</ParamField>

<ParamField body="testId" type="string">
  Run a single test. Omit to run all tests in the project.
</ParamField>

## Response

<ResponseField name="projectId" type="string">
  The project the runs belong to.
</ResponseField>

<ResponseField name="runIds" type="string[]">
  Ids of the created runs — one per test. Poll each with
  [Get a run](/api-reference/get-run).
</ResponseField>

<RequestExample>
  ```bash Run all tests theme={null}
  curl -X POST \
    -H "Authorization: Bearer $CLICKPROOF_API_KEY" \
    -H "Content-Type: application/json" \
    https://clickproof.app/api/v1/projects/YOUR_PROJECT_ID/runs
  ```

  ```bash Run one test theme={null}
  curl -X POST \
    -H "Authorization: Bearer $CLICKPROOF_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"testId":"YOUR_TEST_ID"}' \
    https://clickproof.app/api/v1/projects/YOUR_PROJECT_ID/runs
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "projectId": "7f3a9c21-4e8b-45d2-9a1c-2b6e0f8d1a44",
    "runIds": [
      "b1c2d3e4-1111-2222-3333-444455556666",
      "f7a8b9c0-7777-8888-9999-000011112222"
    ]
  }
  ```
</ResponseExample>

## Errors

| Status | Body                                       | When                                                                        |
| ------ | ------------------------------------------ | --------------------------------------------------------------------------- |
| `400`  | `no build uploaded — POST the build first` | The project has no build.                                                   |
| `400`  | `project has no tests to run`              | No tests exist for the project.                                             |
| `402`  | quota message                              | The team's run quota is exhausted. `runIds` lists any runs already started. |
| `404`  | `project not found`                        | No such project for your team.                                              |