Change virtual users mid-run

A running test is not fixed. From the run’s Live tab you can move the virtual user target and the throughput cap while the load is in flight, pause and resume it, and every change is recorded on the run’s timeline with who made it and when.

Nothing restarts. The run keeps its id, its result series and its report.

Before you start

• The run must be running. A queued or finished run answers 409 RUN_NOT_RUNNING.
• You need the controller role on the run (account members and test editors have it).
• Your executor and your script must support the control. JMeter, k6, Locust and Gatling can move virtual users live; the other executors cannot, and the console says so instead of pretending. Except on Locust, the script also has to be built for it — a Concurrency Thread Group on JMeter, an externally-controlled scenario on k6, the helper opt-in on Gatling. Make your test controllable mid-run is the recipe per engine; What each executor supports at runtime is the full matrix.

Change the virtual user target

1. Open the run and select the Live tab.

2. Set the Virtual users field to the new fleet-wide total and commit it.

   The number you type is always the whole fleet. Underneath the field MaxoPerf shows the divide it will perform — for example 2 000 = 20 runners × 100 — so what each runner is told is never a guess.

3. Watch the ack pill. It counts runners that have confirmed the change: applied 4 987 / 5 000. It normally converges in well under a second.

4. Confirm it landed in the load. The run’s charts get a vertical marker at the moment the change applied, so a step in the VU or throughput series lines up with the change that caused it.

The slider commits on release

Dragging does not emit a change per pixel. The console commits when you let go, and the server additionally coalesces bursts: if a newer value for the same control lands within the coalescing window, the older one is recorded on the timeline as coalesced and never dispatched. It is still visible — a change that was dropped is never dropped silently.

Change the throughput cap

Identical flow, using the Requests per second field. 0 means unlimited.

On k6, throughput is approximate

k6 has no API to change an arrival rate on a running test. MaxoPerf realises an RPS target on k6 by scaling the VU count instead, so the result is an approximation and is labelled approximate everywhere it appears — in the console, in the API response and in the capability matrix. On Locust there is no RPS control at all: Locust models load as users × wait time and has no rate primitive, so the control is disabled with that reason rather than mapped onto a different number wearing an RPS label.

Pause and resume

The Pause toggle stops the load without ending the run — useful when you want to fail something over, take a snapshot, or let a queue drain, and then continue in the same run and the same charts. Resume restores the previous target.

Scope a change to part of the fleet

By default a change applies to every live runner. The scope chips narrow it:

Scope	Use it for
All	the whole fleet (default)
Locations	one cloud region, or one private datacenter
Runners	named individual runners

A scope that resolves to zero live runners is rejected with 422 SELECTOR_NO_MATCHING_RUNNERS rather than accepted and quietly applied to nothing.

The global number keeps being met when the fleet moves

A fleet-wide total divided across N runners silently stops being met the moment N changes. If a runner dies, or you add runners mid-run, MaxoPerf re-divides the current target against the new live count and republishes it automatically. Those revisions appear on the timeline marked system rather than attributed to you.

Plan limits

Increases are capped by your plan’s maxLiveConcurrentVus and maxLiveThroughputRps; going past them returns 403 PLAN_LIMIT_EXCEEDED. Enterprise sets both to -1 (unlimited), so no mid-run increase is refused on that plan.

Decreases are never blocked — including from a run that started above the cap. If your test is melting the system under test, you can always turn it down.

From the API

curl -X PUT "$MAXOPERF_API/v1/runs/$RUN_ID/live-controls/virtual-users" \
  -H "Authorization: Bearer $MAXOPERF_API_KEY" \
  -H "X-Account-Id: $ACCOUNT_ID" \
  -H 'Content-Type: application/json' \
  -d '{"scope":{"type":"all"},"total":2000}'

// 202 Accepted
{ "revision": 7, "perRunner": 100, "runnerCount": 20, "dispatchState": "dispatched", "delivered": true }

The per-runner share is rounded up and never drops below 1, so a small total across a wide fleet cannot be delivered exactly. When that happens the response says so rather than implying an exact split, and the timeline renders the total as approximate:

// 202 Accepted — 7 RPS across 20 runners is 1 each, so the fleet will really run 20
{ "revision": 8, "perRunner": 1, "runnerCount": 20, "clamped": true, "effectiveTotal": 20, … }

clamped is absent whenever the divide is exact. If a decrease comes back clamped, the fleet is too wide for the target — release runners, or accept effectiveTotal as the floor.

Read the outcome back — desired state, capabilities and ack tallies — with GET /v1/runs/:runId/live-controls, the full change log with GET /v1/runs/:runId/live-controls/history, and the exact runners that have not applied a revision with GET /v1/runs/:runId/live-controls/revisions/:revision/acks?status=failed.

Related

• Make your test controllable mid-run
• What each executor supports at runtime
• Live JMeter properties
• Control a Gatling run while it is running