Control Workflow Load with Per‑Workflow Concurrency Limits on Cloudflare Workers

Cloudflare now lets you define a per‑workflow concurrency limit on individual Workflows, restricting the number of concurrent executions. The change is exposed through the concurrency.limit field in the workflow binding, and it applies whether the workflow is declared in wrangler.jsonc, wrangler.toml, or via the Workers API.

What Changed

Previously, a Workflow could consume any portion of the account‑wide concurrency quota, potentially starving other Workflows. The new setting adds a per‑workflow ceiling that is enforced by the platform. Instances that exceed the limit are not rejected; they are placed in a queue and start automatically when running instances finish or move to a waiting state.

Why It Matters to Engineers

• Resource protection: You can shield a database, third‑party API, or any downstream service that degrades under high parallel load by capping the number of simultaneous calls.
• Load balancing: High‑volume Workflows no longer monopolize the account’s total concurrency, allowing smaller or latency‑sensitive Workflows to obtain capacity.
• Predictable scaling: Knowing the maximum parallelism per Workflow simplifies capacity planning and cost estimation.
• Operational safety: Reducing the limit does not abort already‑running instances, preventing abrupt disruption during a limit change.

Implementation Details

Set the limit in the workflow definition. The JSON‑C example below caps the workflow at ten concurrent runs:

{
  "workflows": [
    {
      "name": "my-workflow",
      "binding": "MY_WORKFLOW",
      "class_name": "MyWorkflow",
      "concurrency": {
        "limit": 10
      }
    }
  ]
}

The equivalent TOML snippet is:

[[workflows]]
name = "my-workflow"
binding = "MY_WORKFLOW"
class_name = "MyWorkflow"
[workflows.concurrency]
limit = 10

The limit must be a positive integer and cannot exceed the account‑wide concurrency quota (100 for Workers Free, 50 000 for Workers Paid). Declaring the limit on a workflow that is exported via the Workers API or @cloudflare/config follows the same schema.

Operational and Security Considerations

Because excess instances are queued rather than dropped, you should monitor queue length to detect bottlenecks. A growing queue may indicate that downstream services are slower than expected or that the limit is set too low for the workload. Conversely, a limit that is too high could still saturate the account quota, re‑exposing the original contention problem.

From a security perspective, the limit helps mitigate denial‑of‑service scenarios that arise from uncontrolled parallelism against external endpoints. By capping concurrency, you reduce the risk that a compromised workflow floods a third‑party API with requests.

Changing the limit is a non‑disruptive operation: lowering it does not terminate in‑flight instances, and raising it only expands the ceiling. However, any change should be validated in a staging environment to confirm that queue behavior matches expectations.

Related CloudNinjas coverage: hands-on guides.

What This Means For Practitioners

• Audit existing Workflows and decide whether a per‑workflow limit is needed based on downstream service capacity.
• Introduce concurrency.limit in the workflow configuration files and redeploy.
• Instrument metrics for running instances and queued requests to detect when limits are being hit.
• Review your account‑wide concurrency quota and ensure that the sum of per‑workflow limits stays comfortably below the maximum.
• When adjusting limits, test the impact on queue latency before applying changes to production.