> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/grafana/k6/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`).

<Warning>
  These commands are hidden and primarily intended for advanced use cases. Most users should configure tests upfront rather than dynamically controlling them.
</Warning>

## k6 pause

### Synopsis

```bash theme={null}
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

```bash theme={null}
# 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

```bash theme={null}
k6 resume [flags]
```

### Description

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

### Examples

```bash theme={null}
# Resume test running on default address
k6 resume

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

## k6 scale

### Synopsis

```bash theme={null}
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

```bash theme={null}
# 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

<ParamField path="-u, --vus" type="int">
  Number of virtual users to scale to. Must be less than or equal to max VUs.
</ParamField>

<ParamField path="-m, --max" type="int">
  Maximum available virtual users. This sets the VU pool capacity.
</ParamField>

### 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:

<ParamField path="--address" type="string" default="localhost:6565">
  Address of the k6 REST API server
</ParamField>

## REST API Endpoints

These commands are wrappers around REST API calls:

### PATCH /v1/status

The underlying API endpoint for all control operations:

```bash theme={null}
# 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:

```yaml theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
export K6_ADDRESS=localhost:8080
k6 run script.js
```

## Use Cases

### Manual Load Testing

Manually control load during exploratory testing:

```bash theme={null}
# 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:

```bash theme={null}
#!/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:

```bash theme={null}
# 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:

```bash theme={null}
# 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](/cli/run) - Start a test with the REST API
* [REST API documentation](https://k6.io/docs/misc/k6-rest-api/)
* [externally-controlled executor](https://k6.io/docs/using-k6/scenarios/executors/externally-controlled/)