Load testing

A load test runs a collection over and over with many simulated users at once, so you can see how an API behaves under traffic: how fast it answers, how many requests per second it handles, and when it starts to fail. The virtual users run on your Mac, like Postman’s local performance testing. Scripts and tests run on every request, and charts update every second.

Only test systems you're allowed to load

A load test sends a large number of requests quickly. Against someone else’s API it can look like, and act like, a denial-of-service attack. Only load test servers you own, or ones whose owner has given you written permission. Prefer a staging environment over production, and start small.

12345

A finished ramp-up test: summary metrics, charts per second, and statistics per request.

1. Load profile: Fixed, Ramp up, Spike or Peak
2. Virtual users, duration, start/base users and think time
3. Run Load Test
4. Requests, throughput, average, p95, p99 and error rate
5. Count, errors, average, p90, p95 and max for each request

×

Run a load test

1. Open the collection and click Load Test in its header, or right-click the collection in the sidebar and choose Performance Test.

   A tab named Load test · Collection name opens.

2. Pick a Load profile: Fixed, Ramp up, Spike or Peak. See Load profiles.

3. Set Virtual users and Duration. For any profile other than Fixed, also set Start/base users.

4. Optionally set Think time, a pause each user takes between passes through the collection.

5. Click Run Load Test.

   A progress bar shows how far through the duration the test is. Click Stop to end it early. The charts fill in once a second, and the summary and per-request table appear when the test ends.

The test uses the active environment, your globals, the collection’s variables and your Vault secrets, like the collection runner. Variable changes made by scripts during a load test aren’t saved.

Settings

Setting	Default	Range	What it does
Load profile	Fixed		How the number of active users changes over the test.
Virtual users	10	1 to 500	The most users active at once (the peak for Ramp up, Spike and Peak).
Duration	60 s	5 to 3,600 s, in steps of 5	How long the test runs.
Start/base users	2	1 to 500	Ramp up: users at the start. Spike and Peak: the baseline. Not shown for Fixed. If it’s higher than Virtual users, Virtual users is used.
Think time	0 ms	0 to 10,000 ms, in steps of 50	How long each user waits after a pass through the collection before starting the next.

Load profiles

The profile sets how many virtual users should be active at each moment, as a share of the duration.

Profile	Users over the test	Use it to
Fixed	Virtual users for the whole test.	Measure steady-state performance at a known load.
Ramp up	Starts at Start/base users and rises in a straight line to Virtual users by 70% of the duration, then holds there.	Find the point where response times start to climb.
Spike	Start/base users, then all Virtual users from 40% to 60% of the duration, then back to the base.	See how the API handles a sudden burst and whether it recovers.
Peak	Rises from the base to Virtual users over the first 30%, holds until 70%, then falls back to the base by the end.	Simulate a busy period with a build-up and a wind-down.

For example, a Peak test with 100 virtual users, 20 base users and a 60 second duration rises from 20 to 100 users over the first 18 seconds, holds 100 users until 42 seconds, and falls back to 20 by 60 seconds.

How virtual users work

• Each virtual user sends every HTTP and GraphQL request in the collection, in order, then starts again from the top, until the duration ends. Other protocols (gRPC, WebSocket and so on) are left out of load tests.
• Each user keeps its own copy of the variables, so values a script sets (such as a token from a login request) carry over to that user’s later requests.
• Pre-request scripts, post-response scripts and tests run on every request.
• The app checks the profile ten times a second. When the profile asks for more users, new ones start right away. When it asks for fewer, the newest users stop at the start of their next pass.
• When the duration ends, users stop before sending another request.

Your Mac is the load generator

All users run on this Mac, so very high user counts are limited by its CPU and network. If response times rise while the server looks idle, the bottleneck may be the client. For bigger tests, run cloakctl perf on a machine closer to the server.

Read the results

Summary

The numbers at the top right appear when the test finishes.

Metric	Meaning
requests	Total requests sent during the test.
throughput	Requests per second over the whole test (total requests divided by the elapsed time).
average	Mean response time of every request.
p95	95% of requests were at least this fast.
p99	99% of requests were at least this fast. Shows the slowest tail.
errors	The share of requests that counted as errors, as a percentage. See What counts as an error.

Percentiles use the nearest-rank method: the response times are sorted and the value at that rank is taken.

Charts

Both charts have one point per second of the test, and fill in live while it runs.

Chart	What it shows
Response time (ms)	Two lines: Average and p95 response time of the requests that finished in that second. A red dot marks any second with errors.
Requests/s · users	Blue bars: requests finished in that second. Orange line: the number of active virtual users.

Compare the two charts: if response times climb as the user line rises while requests per second level off, the API has reached its capacity.

Per request

The table lists each request (by its folder path) with:

Column	Meaning
Request	The request’s name, with its folder path.
Count	How many times it was sent.
Errors	How many of those were errors (in red when above 0).
Avg	Mean response time.
p90	90th percentile response time.
p95	95th percentile response time.
Max	Slowest response.

What counts as an error

A request counts as an error when any of these is true:

• It couldn’t be sent or timed out (a connection, DNS or TLS error, for example).
• The response status is 400 or higher.
• One of its tests failed.

So a load test catches both an overloaded server returning 503s and a server that answers 200 with the wrong body, if you have a test for it. Add a response-time test such as pm.expect(pm.response.responseTime).to.be.below(500) to count slow answers as errors too.

Run a load test from the command line

cloakctl perf runs the same test without the app. It reads collections and environments from your workspace.

Terminal

cloakctl perf "Petstore" --vus 50 --duration 120 --profile rampUp -e Staging

Argument or flag	What it does
NAME or FILE.json	A collection in the workspace, or a Postman collection file or OpenAPI spec file.
--vus N	Virtual users. Default 10.
--duration S	Duration in seconds. Default 30.
--profile SHAPE	fixed, rampUp, spike or peak. Default fixed. The start/base users is 2.
--think-time MS	Pause between each user’s passes. Default 0.
-e ENV	An environment by name, or a Postman environment file. Defaults to the active environment.
--workspace DIR	Use a different workspace folder.

It prints a line every second, then a summary with p90, p95 and p99, and one line per request:

Output

Load testing “Petstore”: 50 users, 120s, Ramp up
1s  users 2  141 req/s  avg 12 ms  p95 19 ms  errors 0
2s  users 3  205 req/s  avg 13 ms  p95 21 ms  errors 0
…

24180 requests · 201.4/s · avg 18 ms · p90 27 ms · p95 33 ms · p99 61 ms · errors 0.0%
  Create pet: 8060 req, 0 errors, avg 21 ms, p95 36 ms
  Get pet: 8060 req, 0 errors, avg 16 ms, p95 30 ms
  List pets: 8060 req, 0 errors, avg 17 ms, p95 32 ms

The exit code is 1 when any request counted as an error, and 0 otherwise, so you can fail a CI job on errors. See cloakctl for every command.

AI assistants connected to the Cloak Proxy MCP server can run a load test with the run_load_test tool, which caps the duration at 600 seconds.

Related

Collection runnerCheck correctness before you check speed.

Scripts and testsTests that turn slow or wrong answers into errors.

Mock serversServe examples locally to test a client without the real API.

Test on a slow networkSee your app on a bad connection.