Automate Load Tests
Use the REST API, testvibe CLI, or MCP server to create, update, delete, list, and run load tests and read their measurements. The CLI supports features or paths, users, duration, a single ramp, repeats, and thresholds. Multi-stage ramps are configured in the app. Cloud API access requires Team, Business, or Enterprise.
Authenticate with a tvb_… key from Settings → CLI & API keys. See CLI & API keys.
Dispatch a load test from the terminal, gate a pipeline on its exit code, and read the completed result back.
List your load tests
- CLI
- REST
- AI tool (MCP)
testvibe load list
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)
# 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 --timeout 3600
Add --url https://staging.example.com to override the target for this run.
--timeout <seconds> caps how long --wait polls — worth raising for a long soak test, since it defaults to 5400 seconds (90 minutes); --timeout 0 waits indefinitely. The exit code is 0 if the load run passed, 1 if it failed, and 3 if the wait ended before the run did — no verdict, which is not the same as a failure and shouldn't be reported as one. See the CLI wait contract.
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 until a terminal status such as passed, failed, or cancelled; queued and preparing states are still in progress.
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 (and exits 1). 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 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: