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_users is required, and so is one of url, journey_id or mix. 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_time is the limit in seconds, from 1 to 10, 3 if left out. note labels the run, for example “baseline”. exclude_paths lists 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 settings change 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 a live_url where 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, when max_users is 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, the latest measurement (users, average and slowest load time, and whether it was over the limit), how many users have errored and why (bot_errors), the stop_reason once the run has ended, and a hint that says what to do next. For a controlled run, control adds 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. Set charts to false to leave the images out.
  • Returns: users_handled, the highest user count tested, the target (90% of max_users) and whether it was reached, the stop_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-sentence summary and the report_url of 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_id and the state expired, 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), category and description are required. The category is one of database, web_server, app_server, php, caching, cdn, hosting_plan, code, config or other. before and after hold 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, and run_b, the later run. Set charts to false to leave the image out.
  • Returns: both runs side by side (users handled, target reached, page load statistics, report link), a verdict in 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, and pages, 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_wait lists the endpoints with the longest average server wait. normal_pages_baseline gives the same for normal-speed loads. Each page has a har_url to 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. limit is how many of the latest runs to return, up to 60 (30 if left out). Set charts to 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 with report_change, the site’s schedules and a history_url to 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_id and action are required. The actions are:
    • release: start users more users, per_step at a time every every_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.
    • pause and resume: stop all users, and start them again.
    • restart_errored: restart the users that have errored.
    • settings: change the run’s settings or its max_load_time while it runs.
  • Returns: what was done, followed by the same status that get_run_status gives.
  • 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_test under billing. Nothing ramps up or ends on its own: the run ends with stop_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_id is required. state picks which users to list: errored (the default), playing, idle, paused or all. users lists specific user numbers. limit is how many to list, up to 50 (10 if left out). screenshot asks 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. counts gives 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 }
}