# Automate Load Tests

URL: https://docs.testvibe.com/load-testing/automate-load-tests

*Dispatch a load test from a terminal, block until it finishes, then read the profile, the summary and every threshold back as JSON — the shape a CI job needs to decide whether to ship.*

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) , 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.

info
Authenticate with a `tvb_…` key from **Settings → CLI & API keys** . See [CLI & API keys](/account-settings/api-keys) .

## List your load tests

- CLI - REST - AI tool (MCP)

```bash
testvibe load list
```

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

Ask your assistant to use the **`list_load_tests`** tool.

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

## Run a load test

- CLI - REST - AI tool (MCP)

```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.

```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` .

Ask your assistant to use **`run_load_test`** with the load test's name or id, then `wait_for_run` .

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 the app's Load section has the live latency / throughput / error-rate charts.

## Read the results

A pass/fail verdict is enough to gate a build, but not to answer "did it get slower?". `runs show` returns the whole picture as JSON:

```bash
testvibe runs show 1161 --json
```

The `load` block carries three things:

| | | `profile` | what actually ran — mode, engine, virtual users, duration, and the paths or journeys | `summary` | `requests` , `requestRate` , `errorRate` , `peakVus` , and `durationMs` with `min` / `avg` / `p50` / `p90` / `p95` / `p99` / `max` | `thresholds` + `thresholdSummary` | each gate, its expression, and whether it passed — plus `gated` and `allPassed` for a single check 

So a CI step can gate on the exit code and still record the numbers, without opening the app:

```json
"summary": {
  "requests": 95,
  "requestRate": 4.5139,
  "errorRate": 0,
  "peakVus": 5,
  "durationMs": { "p50": 88.96, "p95": 105.23, "p99": 124.46, "max": 133.11 }
},
"thresholdSummary": { "total": 2, "passed": 2, "failed": 0, "gated": true, "allPassed": true }
```

## 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)** 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](/testvibe-api/reference/load/list_load_tests)
- [run_load_test](/testvibe-api/reference/load/run_load_test)

## Related Help

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