> For the complete documentation index, see [llms.txt](https://docs.testvibe.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.testvibe.com/testvibe-api/api-reference/runs/run_suite.md).

# run\_suite

Dispatch runs for several features in one call — one run per feature, on the same spine as [`run_feature`](/testvibe-api/api-reference/runs/run_feature.md). Omit `features` to run **every feature with status `generated`** (the whole runnable suite). Returns the dispatched `runId`s immediately.

{% hint style="info" %}
A feature whose dispatch fails (e.g. no generated tests) is reported per-item with an `error` instead of aborting the rest.
{% endhint %}

## Request

```
POST /api/v1/ops/projects/{project}/runs
```

| Parameter  | In   | Type      | Required | Description                                                                                                                           |
| ---------- | ---- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `project`  | path | string    | yes      | The project's public id.                                                                                                              |
| `features` | body | string\[] | no       | Feature ids or names. Omit to run all `generated` features.                                                                           |
| `config`   | body | string    | no       | Playwright configuration name (default `Default` — see [`list_configs`](/testvibe-api/api-reference/configurations/list_configs.md)). |
| `siteUrl`  | body | string    | no       | Test site URL override.                                                                                                               |

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST -H "Authorization: Bearer $TESTVIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "$TESTVIBE_SERVER/api/v1/ops/projects/$PROJECT/runs"
```

{% endtab %}

{% tab title="CLI" %}

```bash
testvibe run --all --wait        # the whole suite; exits non-zero on any failure
testvibe run Login Checkout --wait
```

{% endtab %}

{% tab title="MCP" %}
Tool **`run_suite`** — `{}` for the whole suite, or `{ "features": ["Login", "Checkout"] }`. Follow each `runId` with `wait_for_run`.
{% endtab %}
{% endtabs %}

## Response

`202 Accepted`

```json
{
  "runs": [
    { "featureId": 12, "featureName": "Login Functionality", "runId": 215 },
    { "featureId": 15, "featureName": "Checkout", "runId": 216 },
    { "featureId": 18, "featureName": "Search", "error": "conflict", "message": "This feature has no generated tests yet — generate them first." }
  ]
}
```

Poll each `runId` with [`wait_for_run`](/testvibe-api/api-reference/runs/wait_for_run.md) / [`get_run`](/testvibe-api/api-reference/runs/get_run.md).

## Errors

| HTTP            | When                                                                |
| --------------- | ------------------------------------------------------------------- |
| `404 not_found` | No such project, or a named feature doesn't exist.                  |
| `409 conflict`  | `features` was omitted and the project has no `generated` features. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.testvibe.com/testvibe-api/api-reference/runs/run_suite.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.