k6 pause/resume/scale

Control running k6 tests via the REST API

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:

Executor	Pause/Resume	Scale
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

• k6 run - Start a test with the REST API
• REST API documentation
• externally-controlled executor