> 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/load-testing/automate-load-tests.md).

# Automate Load Tests

Everything you author in the Load section can be triggered from outside the app: list your load tests and dispatch a run over the [REST API](/rest-api.md), the `testvibe` CLI, or the MCP server your AI tools connect to. You still **configure** load tests in the app (pick journeys or endpoints, users, duration, thresholds) — automation covers the two things you'd script: **listing** them and **running** them.

{% hint style="info" %}
Authenticate with a `tvb_…` key from **Settings → CLI & API keys**. See [CLI & API keys](/account-settings/api-keys.md).
{% endhint %}

## List your load tests

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

```bash
testvibe load list
```

{% endtab %}

{% tab title="REST" %}

```bash
curl -H "Authorization: Bearer $TESTVIBE_API_KEY" \
  "$TESTVIBE_SERVER/api/v1/ops/projects/$PROJECT/load"
```

{% endtab %}

{% tab title="AI tool (MCP)" %}
Ask your assistant to use the **`list_load_tests`** tool.
{% endtab %}
{% endtabs %}

Each load test shows its `id`, `name`, and `status`. Only tests with status `generated` are runnable.

## Run a load test

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

```bash
# Dispatch and return immediately
testvibe load run "Checkout under load"

# Or wait for it to finish (handy as a CI gate)
testvibe load run "Checkout under load" --wait
```

Add `--url https://staging.example.com` to override the target for this run.
{% endtab %}

{% tab title="REST" %}

```bash
curl -X POST -H "Authorization: Bearer $TESTVIBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"siteUrl": "https://staging.example.com"}' \
  "$TESTVIBE_SERVER/api/v1/ops/projects/$PROJECT/load/31/run"
```

Returns `{ "runId": …, "featureId": … }`. Poll the run's status until it leaves `running`.
{% endtab %}

{% tab title="AI tool (MCP)" %}
Ask your assistant to use **`run_load_test`** with the load test's name or id, then `wait_for_run`.
{% endtab %}
{% endtabs %}

A dispatched load run is subject to your plan's load caps and credits — a rejected run comes back with a clear reason. The run shares the normal run spine, so you can read its status with the run tools (`testvibe runs show <runId>`, `wait_for_run`, `get_run`) and watch the live latency / throughput / error-rate charts in the app's Load section.

## Automate on a recurring schedule

The CLI/REST/MCP path above is for **you** (or your CI pipeline) driving a load test on demand. To have TestVibe itself fire a load test on a cron schedule or whenever another run finishes, create an [**Automation**](/run-tests/automations.md) with a **Run a load test** action instead — no external scheduler needed. Each firing dispatches exactly one run of the chosen load test.

## Full reference

Request and response shapes, error codes, and AI-tool setup live in the developer handbook:

* [list\_load\_tests](https://docs.testvibe.com/testvibe-api/reference/load/list_load_tests)
* [run\_load\_test](https://docs.testvibe.com/testvibe-api/reference/load/run_load_test)

## Related Help

* [Create a load test](/load-testing/create-a-load-test.md)
* [Run a load test and read results](/load-testing/run-a-load-test-and-read-results.md)
* [Automations](/run-tests/automations.md)
* [REST API](/rest-api.md)
* [CLI & API keys](/account-settings/api-keys.md)


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.testvibe.com/load-testing/automate-load-tests.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.