How to load test an API in API Spector
Functional testing answers "is this response correct". Performance testing answers a different question: "how does this endpoint behave under load". The two need different tools and different output, so in API Spector they live in different places. Performance testing is its own view, reached from its own icon in the left activity bar, and it does not touch your functional tests.
This guide covers running a load test and reading the result.
Open the Performance view
In the left activity bar, below Flows, there is a new gauge icon labelled Performance testing. Click it. The functional side of the app (collections, requests, assertions) is untouched; this is a separate workspace for load.
The reason it is separate is deliberate. A load test fires the same request or flow hundreds or thousands of times and reports aggregate numbers. Mixing that into the request editor would clutter the day to day work of checking that an API returns the right thing. Keeping it apart means people who only functional test never have to see it.
1. Create a plan and pick a target
Each load test is a named plan in the left panel. Click New plan to add one, and keep as many as you need, for example one per endpoint or one per scenario (a quick smoke run and a heavier soak run of the same endpoint). Plans are saved inline in the workspace, so they travel with the project and show up in Git diffs, the same as your collections.
With a plan selected, choose what it drives with the Target switch:
- Request: pick any HTTP or SOAP request from your collections. Each iteration sends that one request. It runs exactly as you saved it (method, URL, headers, body, auth), and
{{variables}}resolve against the active environment, like a normal send. Unary gRPC requests work here too: each iteration is one call over a shared channel, and the status breakdown shows the gRPC status names (OK, NOT_FOUND, and so on). - Sequence: pick a collection, or a folder inside it. Each iteration runs its requests in order, and variables carry between them, so a login request near the top can set a token the later requests use. This is the common case: load test the real path a client takes through your API, not just one call. The order and the inherited auth and headers are the same as a normal collection run.
- Flow: pick one of your saved visual flows. Each iteration runs the whole flow from start to finish, branching and all. Use it when the scenario has logic a straight sequence cannot express.
WebSocket, Socket.IO, MQTT, and streaming gRPC methods are not listed, since load testing a long-lived connection is a different shape of problem.
2. Choose a load pattern
The load pattern shapes how many users (or how many requests) hit the target over time. Four patterns cover the common shapes, and a live load profile graph under the form shows exactly what you have configured before you run it.
- Basic: hold a set number of virtual users, with an optional ramp up at the start and ramp down at the end. The everyday choice.
- Stepping: start at a number of users and add a step every so often, up to a maximum. Good for finding the point where the system starts to struggle.
- Arrivals: an open model. Instead of a fixed number of users you set a target rate of iterations per second, and the tool spawns users as needed, up to a cap, to hold that rate. Use it to measure throughput, because the load does not back off when responses slow down.
- Custom: author your own stages. Each stage is a duration and a target, held flat or ramped from the previous one, so you can build ramp, hold, and spike profiles by hand.
A virtual user runs iterations of the target back to back. In the closed-model patterns (basic, stepping, custom) you set the number of users directly; in arrivals you set the rate and the user count follows.
There is also an optional Timeout in seconds: a request that passes the cap counts as a failure rather than being waited on forever. Leave it at 0 for no cap.
3. Run it
Click Run load test. A progress bar fills as the run proceeds, and a live row shows completed iterations, active users, the current target, failures, iterations per second, the rolling p95 latency, and elapsed time. If you need to cut it short, Stop ends the run and still reports what it collected.
Everything is sent through the same path as the normal runner, so auth handshakes, body serialization, and any TLS or proxy settings behave identically. For a single-request target, per-request scripts and assertions are skipped, so the timing measures the endpoint and not your script. A flow keeps its steps intact, because a flow's own logic (extracting a token and passing it on) is exactly the scenario being measured.
4. Read the result
When the run finishes, the view fills with the aggregate.
The headline cards:
- Throughput in iterations per second, with requests per second beside it (a flow does several requests per iteration).
- Iteration p95, the time 95 percent of whole iterations came back within, with p99 beside it. The tail matters more than the average, because it is what users feel.
- Error rate, the share of iterations that failed.
- Peak users, the most active at once, and for arrivals how many were dropped because the cap was reached.
A per-second chart shows completed iterations per second as bars with the p95 latency over it, so you can see whether latency climbed as the load held.
The per-step breakdown is the useful part for a flow: one row per request in the sequence, with its count, p95, mean, and failures. It tells you which step (the login, the search, the checkout) is the slow or failing one. A single-request target shows one row.
Below that, the request latency panel breaks out min, mean, p50, p90, p95, p99, and max across every request, with the total data read. Status codes shows the spread of responses, so a batch of 429 or 500 under load is obvious, and Errors lists any connection or timeout failures with their counts.
A sensible first run
For an endpoint or flow you have not tested before, start with the Basic pattern:
- Virtual users: 10
- Ramp up: 5s, hold: 30s
- Timeout: 5 seconds
Read the error rate and the iteration p95. If both look healthy, switch to Stepping and let it climb, for example start at 10, add 10 every 30 seconds, up to 100. The point where the error rate rises or p95 spikes is the capacity figure worth writing down.
Thresholds, think time, and reports
A few options turn a plan into a proper gate rather than a one-off measurement.
Thresholds turn a run into pass or fail. Add one or more gates (for example iteration p95 under 500 ms, or error rate at most 1 percent) and the result shows a clear PASSED or FAILED banner with each gate's actual value beside it. Thresholds are optional; without them a run is just a measurement. On the command line a failed threshold makes the run exit non-zero, so it can gate a CI build.
Think time adds a pause between iterations, so a user-based run behaves more like real users who stop to read between actions instead of hammering as fast as possible. Set a fixed value, or a min and a max for a random pause. It applies to the user-based patterns (basic, stepping, custom).
Realtime results while the run is in flight, a live line tracks iterations per second and p95 as they happen, next to the running counters, so you see trouble building instead of waiting for the end.
HTML report when a run finishes, Export HTML report writes a single self-contained file (no external assets) with the summary, the threshold results, the over-time chart, the per-step table, latency, status codes, and errors. It opens in any browser, so it is easy to attach to a ticket or hand to someone who does not have the app.
Run it from the command line
Every plan also runs headless, so a load test can gate a release the same way your functional tests do:
api-spector perf run "Checkout flow" --workspace ./ --environment staging
The exit code is non-zero when a threshold fails, so a CI job fails the build when the API gets too slow or starts erroring under load. Add --out report.html for a report artifact, or --json to pipe the numbers elsewhere. api-spector perf list shows the plans in a workspace.
You can also override the load profile per run without editing the plan, which is how one plan serves both a quick pull-request smoke and a heavier nightly:
# lighter check on every pull request
api-spector perf run "Checkout flow" --workspace ./ --vus 10 --duration 30s
# heavier nightly, with a stricter gate
api-spector perf run "Checkout flow" --workspace ./ --vus 200 --duration 10m \
--threshold "iteration_p95 lt 800" --threshold "error_rate lte 1"
Why it is built this way
Load testing is easy to get wrong by making it feel like a stress button bolted onto the request editor. Treating it as its own view keeps two audiences happy at once: the person who just wants to check an API keeps a clean, simple editor, and the person measuring capacity gets a focused screen with the numbers that matter. Nothing leaves your machine, and the same request you load test is the one you functional test, so there is nothing to keep in sync.