A Supervisor load test opens your site in real browsers, one per user, and adds users until the site slows down. These ten commands start a test, follow it and explain the result. The examples use the made-up site example.com, and the values in them are invented to show the shape of an answer.
A load test sends real traffic, so the domain must be verified first with verify_site.
start_load_test
Starts a load test. Left to itself, the test is an automatic ramp: it starts with a few users, adds more in steps, and stops when the average page load time stays above the limit. The number of users it reached before that is what the site handles. An agent uses it for the baseline run and again after every change.
The users either explore the site by following links from a start address, run a journey, or do a mix of both. With control set to manual nothing ramps on its own, and the agent drives the users with control_load_test.
- Inputs:
max_usersis required, and so is one ofurl,journey_idormix. A mix has 2 to 5 entries on one site, each a journey or plain exploring, with percents that add up to 100.max_load_timeis the limit in seconds, from 1 to 10, 3 if left out.notelabels the run, for example “baseline”.exclude_pathslists up to 20 paths the browsers must not visit. They are added to the defaults, which keep exploring users away from sign-in, sign-out, payment and admin pages. - Settings: the optional
settingschange the browsers’ user agent, whether Google Analytics is blocked (it is by default), each user’s network speed, the window size, how users explore, when a single user counts as errored and what happens to errored users. - Returns: the
run_id, what was charged and the balance after it, how the ramp goes, when the run stops by itself, the excluded paths and alive_urlwhere you can watch the test. - Cost and effect: an automatic test costs 1 credit per 10 users of
max_users, rounded up, charged when it starts. A controlled test is charged per user-minute while it runs. Only one test per site can run at a time. The run stops by itself when the load time stays over the limit, when 20% or more of the users have errored once at least 10 are running, whenmax_usersis reached, or after 60 minutes.
Every request the test browsers send carries the header X-Supervisor-Run with the run’s id, so the traffic can be found in your server logs.
Example
“Run a baseline load test of example.com with up to 100 users.”
{
"run_id": "11111111-2222-4333-8444-555555555555",
"url": "https://example.com/",
"max_users": 100,
"max_load_time": 3.0,
"credits_charged": 10,
"balance_after": 40,
"stops_when": "average load time stays above 3.0s, 20%+ of bots error (once 10+ are running), 100 users are reached, or after 60 minutes",
"next": "Poll get_run_status every ~15s; read your server logs for this time window.",
"live_url": "https://loadtest.supervisor.com/..."
}
get_run_status
Says how far a run has got. An agent calls it every 15 seconds or so while a test runs, and gives you the live_url so you can watch too.
- Inputs:
run_id. - Returns: the
state, the time elapsed,current_users, thelatestmeasurement (users, average and slowest load time, and whether it was over the limit), how many users have errored and why (bot_errors), thestop_reasononce the run has ended, and ahintthat says what to do next. For a controlled run,controladds how many users are prepared, ready and released, whether the run is paused, the minutes left and the credits charged so far. - Cost and effect: free. It only reads.
Example
“How is the test going?”
{
"run_id": "11111111-2222-4333-8444-555555555555",
"state": "active",
"elapsed_seconds": 95,
"current_users": 40,
"latest": { "users": 40, "avg_load_time": 0.8, "max_load_time": 2.1, "over_limit": false },
"errored_bots": 0,
"hint": "Running. Users increase step by step.",
"live_url": "https://loadtest.supervisor.com/..."
}
get_run_result
Gives the result of a run: how many users the site handled with the average load time under the limit. An agent calls it when the status says the run has finished, and reads the same numbers you see in the web report.
- Inputs:
run_id. Setchartsto false to leave the images out. - Returns:
users_handled, the highest user count tested, the target (90% ofmax_users) and whether it was reached, thestop_reason, page load statistics (count, average, 95th percentile, slowest, and how many took 2 seconds or more), the load time at each user step, the five slowest addresses, why users errored, the changes recorded for the run, a one-sentencesummaryand thereport_urlof the web report. A journey run adds each step’s timings and failures, a mix adds the same per entry, and a controlled run adds its timeline and the load time over time. - Images: two charts, load time per user step and the spread of page load times.
- Cost and effect: free. It only reads. When a run reaches its target, the site did not hit its limit, so the number is not its capacity. The summary says so and suggests a run with more users.
Example
“What did the baseline show?”
{
"run_id": "11111111-2222-4333-8444-555555555555",
"finished": true,
"users_handled": 60,
"highest_users_tested": 70,
"target_users": 90,
"target_reached": false,
"page_loads": { "count": 1800, "avg": 1.2, "p95": 3.4, "max": 9.8, "over_2s": 240 },
"summary": "Handled 60 users with average load time under 3.0s.",
"slowest_urls": [{ "url": "https://example.com/search", "load_time": 9.8 }],
"report_url": "https://loadtest.supervisor.com/..."
}
stop_load_test
Stops a running test at once. An agent uses it when you ask it to stop, when the site is clearly in trouble, or to end a controlled run that has given its answer.
- Inputs:
run_id. - Returns: the
run_idand the stateexpired, which means the run has ended. - Cost and effect: the browsers stop sending traffic. A controlled run stops being charged. Stopping a run that has already ended does nothing.
Example
“Stop the test now.”
{ "run_id": "11111111-2222-4333-8444-555555555555", "state": "expired" }
report_change
Records the one change that was made after a run: what was changed, the old value and the new value. An agent calls it after you have approved a change and before the next run, so that a later comparison can show which change helped.
- Inputs:
run_id(the run the change responds to),categoryanddescriptionare required. The category is one ofdatabase,web_server,app_server,php,caching,cdn,hosting_plan,code,configorother.beforeandafterhold the old and the new value. - Returns: the recorded change and a reminder to run again with the same number of users.
- Cost and effect: free. It stores a note in Supervisor. It changes nothing on your server: your agent makes the change itself, with your approval.
Example
“Raise the PHP worker limit to 20, and record it.”
{
"recorded": {
"category": "php",
"description": "Raised the PHP-FPM worker limit because workers ran out at 60 users",
"before": "pm.max_children = 5",
"after": "pm.max_children = 20",
"at": "2026-11-16T10:42:00Z"
},
"next": "Run start_load_test again with the same max_users, then compare_runs."
}
compare_runs
Compares two runs of the same site, before and after, and says whether the later one is better. An agent calls it after the second run, and keeps or reverts the change by the verdict.
- Inputs:
run_a, the earlier run, andrun_b, the later run. Setchartsto false to leave the image out. - Returns: both runs side by side (users handled, target reached, page load statistics, report link), a
verdictin words, the changes recorded between the two runs, and the load time at each user step for both. Journey runs add a step-by-step comparison, and mixes add one per entry. - How it judges: by users handled. When both runs reached their target, where the ramp stopped means little, so it judges by page load times and calls a change in the 95th percentile of 15% or more better or worse.
- Images: one chart with both runs.
- Cost and effect: free. It only reads. One run on each side proves little when a problem comes and goes, and the answer’s note says to repeat the later run in that case.
Example
“Did the change help?”
{
"before": { "run_id": "11111111-2222-4333-8444-555555555555", "users_handled": 60, "target_reached": false },
"after": { "run_id": "66666666-7777-4888-8999-000000000000", "users_handled": 94, "target_reached": true },
"verdict": "improved: the later run reached the target (60 -> 94 users)",
"changes_between": [{ "category": "php", "before": "pm.max_children = 5", "after": "pm.max_children = 20" }]
}
get_slow_requests
Shows what was slow inside the slowest page loads of a run: which requests, how long the server took to answer each, and which endpoints were slow across those pages. An agent uses it to know what to look for in the server logs.
The test browsers save a full request record (a HAR file) of every page load that takes 2 seconds or more, and of a sample of the normal ones for comparison.
- Inputs:
run_id, andpages, how many of the slowest page loads to look at, from 1 to 10 (5 if left out). - Returns:
pages, each with its address, load time, the user count at the time and its eight slowest requests (status, total time, server wait, download time, size and type).endpoints_by_server_waitlists the endpoints with the longest average server wait.normal_pages_baselinegives the same for normal-speed loads. Each page has ahar_urlto download the full record. - Cost and effect: free. It only reads. The download links stop working after about 7 days, but the summary is saved with the run.
Example
“Which requests made the slow pages slow?”
{
"run_id": "11111111-2222-4333-8444-555555555555",
"pages": [
{
"url": "https://example.com/search?q=shoes",
"load_time": 9.8,
"users": 70,
"slowest_requests": [
{ "method": "GET", "url": "https://example.com/api/search?q=shoes", "status": 200, "time_ms": 8900, "wait_ms": 8700 }
]
}
],
"endpoints_by_server_wait": [
{ "endpoint": "GET example.com/api/search", "count": 5, "avg_wait_ms": 7400, "max_wait_ms": 8700 }
]
}
get_site_history
Shows a site’s load tests over time, whether they were started on the web, by an agent or by a schedule. An agent uses it to see the trend, and to check that a site has not become slower since the last time.
- Inputs:
url, a site address or a domain.limitis how many of the latest runs to return, up to 60 (30 if left out). Setchartsto false to leave the image out. - Returns:
runs, each with its time, kind, user count, users handled, whether the target was reached, average, 95th percentile and slowest page load, errors and any regressions found against earlier runs. Also the changes recorded withreport_change, the site’s schedules and ahistory_urlto the same history on the web. - Images: one trend chart.
- Cost and effect: free. It only reads. The history is kept after a run’s detailed data has been deleted. Runs with different user counts are not directly comparable.
Example
“Has example.com got slower this autumn?”
{
"domain": "example.com",
"runs": [
{ "at": "2026-10-05T03:00:00Z", "kind": "scheduled", "max_users": 100, "users_handled": 94, "target_reached": true, "p95_load_time": 1.4 },
{ "at": "2026-11-02T03:00:00Z", "kind": "scheduled", "max_users": 100, "users_handled": 70, "target_reached": false, "p95_load_time": 3.9 }
],
"history_url": "https://loadtest.supervisor.com/example.com/.../load/history"
}
control_load_test
Drives a controlled run, one started with control set to manual. In a controlled run the browsers are prepared and wait, and the agent decides when users start, pause and resume. An agent uses it for a soak test (hold a steady number of users for an hour), a spike (release many at once) or to try a fix without starting a new run.
- Inputs:
run_idandactionare required. The actions are:release: startusersmore users,per_stepat a time everyevery_seconds(10 users every 10 seconds if left out).prepare: grow or shrink the number of waiting browsers. Big releases start faster when the browsers are prepared first.pauseandresume: stop all users, and start them again.restart_errored: restart the users that have errored.settings: change the run’s settings or itsmax_load_timewhile it runs.
- Returns: what was done, followed by the same status that
get_run_statusgives. - Cost and effect: a controlled run is charged for the users it holds, prepared or playing, for each minute. The rate is in the answer of
start_load_testunderbilling. Nothing ramps up or ends on its own: the run ends withstop_load_test, at its time limit (30 minutes unless you set 5 to 120), or when credits run out. When the load time stays over the limit or too many users error, the run pauses and waits.
Example
“Release 50 users, 10 at a time, and hold them.”
{
"run_id": "11111111-2222-4333-8444-555555555555",
"action": "release",
"done": { "released": 50, "user_numbers": "1-50", "total_released": 50, "all_started_in_seconds": 40 },
"state": "active",
"control": { "prepared": 50, "ready": 50, "released": 50, "paused": false, "minutes_left": 27 }
}
inspect_users
Looks at single users of a run: what state each is in, and when and why it last errored. With screenshot it also shows what the browsers of up to three of them display right now. An agent uses it when users error and the error text alone does not explain what they ran into.
- Inputs:
run_idis required.statepicks which users to list:errored(the default),playing,idle,pausedorall.userslists specific user numbers.limitis how many to list, up to 50 (10 if left out).screenshotasks for the pictures and works only while the run is going. - Returns:
users, each with its number, state, its last error (the kind, the message, the address and the time) and, with a screenshot, the page it was on.countsgives the number of users in each state. - Images: up to three screenshots. They can take up to 15 seconds to arrive.
- Cost and effect: free. It only reads. To look at errored users as they failed, start the run with the setting that holds errored users, then restart them with
control_load_test.
Example
“Some users are failing. Show me what they see.”
{
"run_id": "11111111-2222-4333-8444-555555555555",
"state": "errored",
"users": [
{
"user": 12,
"state": "errored",
"errored_at": "2026-11-16T10:21:07Z",
"last_error": { "type": "timeout", "url": "https://example.com/cart", "at": "2026-11-16T10:21:07Z" },
"page": "https://example.com/cart",
"screenshot": "image 1"
}
],
"counts": { "errored": 3, "playing": 47, "idle": 0, "paused": 0 }
}