---
title: "Throughput Controller"
description: "Configure the JMeter Throughput Controller logic controllers: properties, defaults, and practical usage notes for building reliable load tests."
url: https://docs.jmeter.ai/components/throughput-controller/
lastUpdated: 2026-10-01
source: docs.jmeter.ai
---

# Throughput Controller

*Part of the **Logic Controllers** category. Also documented in context in the [full Component Reference](/user-manual/component-reference/#throughput-controller).*

**TL;DR:** the Throughput Controller runs its children only a percentage of the time (or an exact total count), letting you model realistic traffic mixes — e.g. 70% browse, 20% search, 10% checkout — inside one Thread Group.

![Throughput Controller](/images/screenshots/throughput_controller.png)

The Throughput Controller allows the user to control how often it is executed.
There are two modes:

- percent execution
- total executions

**`Percent executions`**
: causes the controller to execute a certain percentage of the iterations through the test plan.

**`Total executions`**
: causes the controller to stop executing after a certain number of executions have occurred.

Like the Once Only Controller, this setting is reset when a parent Loop Controller restarts.

> **Note**
> This controller is badly named, as it does not control throughput.
> Please refer to the [Constant Throughput Timer](/components/constant-throughput-timer/) for an element that can be used to adjust the throughput.

> **Note**
> The Throughput Controller can yield very complex behavior when combined with other controllers - in particular with interleave or random controllers as parents (also very useful).

| Name | Required | Description |
| --- | --- | --- |
| Name | No | Descriptive name for this controller that is shown in the tree. |
| Execution Style | Yes | Whether the controller will run in percent executions or total executions mode. |
| Throughput | Yes | A number.  For percent execution mode, a number from `0`-`100` that indicates the percentage of times the controller will execute.  “`50`” means the controller will execute during half the iterations through the test plan.  For total execution mode, the number indicates the total number of times the controller will execute. |
| Per User | No | If checked, per user will cause the controller to calculate whether it should execute on a per user (per thread) basis.  If unchecked, then the calculation will be global for all users.  For example, if using total execution mode, and uncheck “`per user`”, then the number given for throughput will be the total number of executions made.  If “`per user`” is checked, then the total number of executions would be the number of users times the number given for throughput. |

### Common gotchas

- **“Percent Execution”** is evaluated per-thread, per-loop — it’s a probability each time the controller is reached, not a hard global ratio across the whole test. Over a long run the actual percentage converges close to the target, but short tests can drift.
- **“Total Executions”** runs the children an exact number of times total across *all* threads, then goes idle — different semantics from percent mode, useful for “run this exactly N times regardless of load.”
- If overall throughput looks stuck regardless of this controller’s settings, the bottleneck is usually elsewhere (threads, pacing, or the target service) — see [Throughput stuck](/topics/errors/throughput-stuck/).
- Combine with a [Constant Throughput Timer](/components/constant-throughput-timer/) when you need an absolute requests/minute cap rather than a relative execution ratio.

## Related

- [Logic Controllers & Flow Control](/topics/logic-controllers-flow-control/)
- [Throughput stuck](/topics/errors/throughput-stuck/)
- [Full Component Reference](/user-manual/component-reference/)
- [Functions and Variables](/user-manual/functions/)