> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-platform/2023-2/studio/optimize-workflow-engine-performance/configure-rate-limiting/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Configure rate limits

> How to configure rate limits for the workflow engine's task workers in Itential Platform.

This topic explains how to configure rate limits for the workflow engine's task workers.

## Prerequisites

* Platform 6.3 or newer installed
* System administrator access to modify Platform configuration
* Access to the workflow engine configuration API (for runtime configuration)

## Configuration parameters

Rate limiting parameters are set at the Platform instance level in environment variables, your `.properties` configuration file, or your profile document.

| Property name (`.properties`)   | Description                                                                                                              | Type    | Default | Minimum | Maximum |
| :------------------------------ | :----------------------------------------------------------------------------------------------------------------------- | :------ | :------ | :------ | :------ |
| `task_worker_rate_limit`        | The maximum number of tasks to run per period. Set to `0` to disable the rate limiter.                                   | Integer | 0       | 0       | None    |
| `task_worker_rate_limit_period` | The time period in seconds for the task worker rate limit.                                                               | Integer | 1       | 1       | None    |
| `task_worker_thread_count`      | The number of worker threads available for task processing. All threads share the configured rate limit. Platform 6.5.1+ | Integer | 1       | 1       | 4       |

### Parameters explained

#### Task worker rate limit

Primary rate limit control for task execution.

* Set to a positive integer to enable rate limiting.
* Set to `0` to disable completely.
* Represents the maximum number of tasks that can execute per period.

#### Task worker rate limit period

Defines the time window (in seconds) for the rate limit.

* Set to a positive integer (seconds).
* Works with `task_worker_rate_limit` to define the execution rate.
* Example: `task_worker_rate_limit=100` with `task_worker_rate_limit_period=1` = 100 tasks per second.

In most cases, use the default period of one second unless you need to rate limit to slower than one task per second.

#### Task worker thread count

Platform 6.5.1+

Controls how many task worker threads run within the Platform instance.

* Each worker processes tasks concurrently.
* All workers share the configured rate limit.
* More workers can improve CPU utilization and throughput.
* Example: Three task workers at 100 tasks per period total (33 per worker) can better utilize available CPU while maintaining the same rate limit.
* Default: 1 task worker.
* Maximum: 4 task workers. Itential Platform doesn't allow values above 4. The task worker uses every thread you allocate to it, and setting this too high can consume all available CPU and memory resources and degrade overall system performance, including API responsiveness and health check reliability.

For guidance on choosing and adjusting a value within this range, see [Tune rate limits](/itential-platform/studio/workflows/optimize-workflow-engine-performance/tune-rate-limits).

## Configuration approach

Rate limiting can be set at startup and adjusted at runtime through the workflow engine API.

**At startup:** Set in Platform-level environment variables, your `.properties` configuration file, or your profile document. Configuration loads when the workflow engine starts and persists across restarts.

**At runtime:** Adjust via the workflow engine HTTP API without a restart. Changes take effect immediately but are not persisted across restarts unless also updated in configuration files.

## Configure at startup (persistent)

#### Determine appropriate rate limits

Choose rate limits based on system resource capacity (CPU, memory), typical workflow volumes and patterns, peak usage times, and downstream service capacity. Monitor your system under typical load and adjust based on observed performance.

#### Set configuration

Set rate limit parameters in your Platform-level configuration:

```bash
task_worker_rate_limit=100
task_worker_rate_limit_period=1
task_worker_thread_count=2
```

#### Restart the Platform

Restart your Itential Platform instance to load the configuration changes.

#### Verify configuration

Verify the configuration has been applied using one of these options:

**Option 1: Check system logs**

Open the workflow engine log files and look for entries confirming rate limit settings, for example, "Task rate limit enabled at X tasks per Y seconds" and "Number of task workers: X." Verify the logged values match your configuration.

**Option 2: View in Admin Essentials**

Navigate to Admin Essentials, select **Configuration** from the left sidebar, locate the `task_worker_*` configuration parameters, and verify the values match your configuration.

If values don't match or no initialization messages appear, check configuration file syntax, verify the configuration is at the Platform level, ensure the Platform version is six or newer, and review system logs for configuration errors.

## Configure at runtime (immediate, not persistent)

Use the runtime API to adjust rate limits immediately without restarting services. Changes take effect right away but are not persisted across restarts.

#### Call the configuration API

Parameters:

* `task_worker_rate_limit`
* `task_worker_rate_limit_period`
* `task_worker_thread_count`

Example API call:

```bash
curl -L -g -X PUT 'http://localhost:3000/workflow_engine/workers/rate_limit?token=••••••' \
-H 'Content-Type: application/json' \
-d '{
    "rateLimit": 10,
    "rateLimitPeriod": 1,
    "threadCount": 2
}'
```

#### Verify configuration

Query the configuration API to confirm the new values:

```bash
curl -L -g -X GET 'http://localhost:3000/workflow_engine/workers/rate_limit?token=••••••'
```

#### Update configuration files for persistence (recommended)

For production deployments, update configuration files to match your runtime settings to ensure they persist across restarts.

Runtime API changes override configuration file settings until Platform restart. After a restart, configuration loads from files.

## Configuration examples

### Basic task rate limiting

Enable task rate limiting at 50 tasks per second:

```bash
task_worker_rate_limit=50
task_worker_rate_limit_period=1
```

### Rate limiting slower than one task per second

Configure rate limiting for very slow task execution:

```bash
task_worker_rate_limit=1
task_worker_rate_limit_period=5
```

Result: one task per five seconds (0.2 tasks per second).

### Disable rate limiting

```bash
task_worker_rate_limit=0
```

Task workers process tasks as quickly as possible without rate limiting.

### Task rate limiting with multiple workers

Enable task rate limiting with multiple workers to better utilize CPU:

```bash
task_worker_rate_limit=150
task_worker_rate_limit_period=1
task_worker_thread_count=3
```

Result: 150 tasks per second total, \~50 tasks per second per worker.

### Adjust for CPU cores

**Small instance (4 cores):**

```bash
task_worker_rate_limit=100
task_worker_rate_limit_period=1
task_worker_thread_count=2
```

Result: 100 tasks per second total, \~50 tasks per second per worker.

**Large instance (12 cores):**

```bash
task_worker_rate_limit=200
task_worker_rate_limit_period=1
task_worker_thread_count=3
```

Result: 200 tasks per second total, \~67 tasks per second per worker.

`task_worker_thread_count` is capped at 4. Start with a lower value and increase incrementally. See [Tune rate limits](/itential-platform/studio/workflows/optimize-workflow-engine-performance/tune-rate-limits).

> How to configure rate limits for the workflow engine's task workers in Itential Platform.