Docs menu

Operate

Load testing

Send steady or climbing traffic at one of your apps and see latency percentiles, errors, the rate it sustained and where it started to break.

Explain it

A load test sends your app lots of requests at a rate you choose, for up to ten minutes, and shows how fast it answered, how many failed, and where it started to struggle. Find out before your users do.

How to do it: open an app's Metrics tab and use Load test: choose the page, how many requests a second and for how long.

"Load test my API at 50 requests a second for two minutes."

Find out how an app behaves under traffic before your users do. A load test sends requests to one of the project's running apps at a rate you choose for up to ten minutes. It reports how fast the app answered, how many requests failed and where it started to struggle.

Run one

On an app's Metrics tab, under Load test, choose the path, the rate and how long. Or:

API
POST /v1/services/:id/load-tests
{"path": "/api/products", "rps": 100, "durationSeconds": 60, "rampSeconds": 30, "thresholds": {"p95Ms": 300, "errorRate": 0.01}}
GET /v1/load-tests/:id
FieldMeaning
rpsRequests a second to reach (the operator sets the maximum, 500 by default)
durationSeconds5 to 600
rampSecondsClimb from 1 request a second to rps over this long. A climb shows the rate where things break.
method, headers, bodyFor APIs that need them
thresholdsp95Ms and errorRate: the test passes only if it stays under both

Only the project's own running apps can be tested. Requests carry User-Agent: cli-load-test and an X-CLI-Load-Test header, so you can find or exclude them in logs.

Reading the result

  • Latency: p50, p90, p95, p99 and the slowest, in milliseconds. p95 is the one to watch: 1 in 20 requests is slower than this.
  • Errors: responses of 400 and above, timeouts and connection failures, counted by status.
  • Sustained rate: what was actually achieved. If the app falls behind, requests that would have piled up past the timeout aren't sent, and the result says how many.
  • Breaking point: the first second where errors passed 5% or p95 more than doubled from the start, with the rate at that moment.
  • Compared with the last test: the change in p95, so you can see whether a deploy made things faster or slower.

Things to know

Edge rules apply to tests too: a rate limit will show up as 429 errors (/docs/edge-protection). Autoscaling reacts to the test like real traffic, and copies it adds are billed as usual. A test costs a tenth of a cent per thousand requests; the X-CLI-Dry-Run: true header shows the estimate first. Agents use cli_load_test.