Skip to main content

​
k6 pause/resume/scale

Control a running k6 test through REST API commands.

​
Description

While a k6 test is running with the k6 run command, it exposes a REST API that allows you to:
  • Pause - Temporarily stop test execution
  • Resume - Continue a paused test
  • Scale - Dynamically adjust the number of VUs
These commands interact with the k6 REST API server (default: localhost:6565).
These commands are hidden and primarily intended for advanced use cases. Most users should configure tests upfront rather than dynamically controlling them.

​
k6 pause

​
Synopsis

k6 pause [flags]

​
Description

Pause a currently running test. When paused:
  • VUs stop executing new iterations
  • Current iterations complete
  • The test timer continues
  • Metrics collection continues

​
Examples

# Pause test running on default address
k6 pause

# Pause test running on custom address
k6 pause --address localhost:6566

​
Use Cases

  • Debug issues during test execution
  • Wait for external system stabilization
  • Manually control test phases

​
k6 resume

​
Synopsis

k6 resume [flags]

​
Description

Resume a paused test. VUs will continue executing iterations from where they left off.

​
Examples

# Resume test running on default address
k6 resume

# Resume test running on custom address  
k6 resume --address localhost:6566

​
k6 scale

​
Synopsis

k6 scale [flags]

​
Description

Dynamically scale the number of VUs in a running test. You can adjust:
  • Active VUs (--vus) - Currently executing VUs
  • Max VUs (--max) - VU capacity/pool size
At least one of --vus or --max must be specified.

​
Examples

# Scale to 50 VUs
k6 scale --vus 50

# Increase max VUs capacity
k6 scale --max 100

# Scale both active and max VUs
k6 scale --vus 50 --max 100

# Scale test on custom address
k6 scale --vus 75 --address localhost:6566

​
Flags

​
-u, --vus
int
Number of virtual users to scale to. Must be less than or equal to max VUs.
​
-m, --max
int
Maximum available virtual users. This sets the VU pool capacity.

​
Constraints

  • Active VUs cannot exceed max VUs
  • Cannot scale beyond resource limits
  • Some executors don’t support dynamic scaling

​
Global Flags

All control commands support:
​
--address
string
default:"localhost:6565"
Address of the k6 REST API server

​
REST API Endpoints

These commands are wrappers around REST API calls:

​
PATCH /v1/status

The underlying API endpoint for all control operations: 
# Pause
curl -X PATCH http://localhost:6565/v1/status \
  -H "Content-Type: application/json" \
  -d '{"paused": true}'

# Resume
curl -X PATCH http://localhost:6565/v1/status \
  -H "Content-Type: application/json" \
  -d '{"paused": false}'

# Scale
curl -X PATCH http://localhost:6565/v1/status \
  -H "Content-Type: application/json" \
  -d '{"vus": 50, "vus-max": 100}'

​
Output

All commands return the current test status in YAML format: 
status: running
paused: false
vus: 50
vus-max: 100
tainted: false
Fields:
  • status - Current test state (init, running, paused, finished)
  • paused - Whether the test is paused
  • vus - Current active VUs
  • vus-max - Maximum VU capacity
  • tainted - Whether the test has been modified during execution

​
Enabling the API Server

By default, the REST API is available on localhost:6565. To customize: 
# Run test with custom API address
k6 run --address localhost:8080 script.js

# Disable the API server
k6 run --address "" script.js
Set via environment variable: 
export K6_ADDRESS=localhost:8080
k6 run script.js

​
Use Cases

​
Manual Load Testing

Manually control load during exploratory testing: 
# Start with low load
k6 run --vus 1 --duration 10m script.js &

# Gradually increase
k6 scale --vus 10
sleep 60
k6 scale --vus 50
sleep 60
k6 scale --vus 100

​
Reactive Scaling

Adjust load based on external metrics: 
#!/bin/bash
while true; do
  CPU=$(get_target_cpu_usage)
  if [ $CPU -gt 80 ]; then
    k6 scale --vus $(($(get_current_vus) - 10))
  fi
  sleep 30
done

​
Debugging

Pause execution to investigate: 
# Test starts running
k6 run script.js &

# Issue detected, pause to investigate
k6 pause

# Investigate the issue...
# Resume when ready
k6 resume

​
Coordinated Testing

Synchronize multiple test instances: 
# Start multiple tests paused
k6 run --paused --address :6565 script.js &
k6 run --paused --address :6566 script.js &

# Start all at once
k6 resume --address :6565 &
k6 resume --address :6566 &

​
Limitations

​
Executor Compatibility

Not all executors support dynamic control:
ExecutorPause/ResumeScale
shared-iterations✅❌
per-vu-iterations✅❌
constant-vus✅✅
ramping-vus✅⚠️
constant-arrival-rate✅✅
ramping-arrival-rate✅⚠️
externally-controlled✅✅
⚠️ = Limited support (may conflict with ramping schedule)

​
State Consistency

When pausing/resuming:
  • Test duration continues
  • Iterations in progress complete
  • Some timing may be affected
  • Metrics reflect actual execution time

​
Resource Limits

Scaling is constrained by:
  • System memory
  • CPU cores
  • Network connections
  • File descriptors

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us