Rate-Limit Execution Creation with Quotas

Cap the number of executions created within a time window, at the flow, namespace, or tenant level. This is different from concurrency, which limits how many executions run simultaneously.

Each quota specifies a duration (the time window and the unique identifier for that quota entry), a limit (the maximum executions allowed in that window), and a behavior (what happens when the limit is exceeded).

Quota properties

Each entry in the quotas list has three required properties:

Behavior options

• CANCEL — the execution is immediately marked as CANCELLED before any tasks run.
• FAIL — the execution is immediately marked as FAILED before any tasks run.

Quota levels

Flow level

Define quotas directly on a flow using the quotas property in the flow YAML. These quotas apply only to that specific flow.

id: my_flow
namespace: company.team

quotas:
  - behavior: CANCEL
    limit: 10
    duration: PT1H

Namespace level

Define quotas on a namespace to apply limits to all flows within that namespace. Navigate to Namespaces, open the target namespace, click Edit, and scroll to the Quotas section.

Namespace quotas apply to every flow whose namespace matches or is a child of the configured namespace.

Tenant level

Define quotas on a tenant to apply limits across all flows in the entire tenant. In Instance Owner, click Quota Limits in the sidebar, then Administer on the target tenant.

Evaluation order

When an execution is triggered, quotas are evaluated from the most specific level to the most general:

1. Flow-level quotas are checked first.
2. Namespace-level quotas are checked next, from the most general ancestor namespace down to the flow’s own namespace.
3. Tenant-level quotas are checked last.

If a quota at a more specific level is exceeded, the execution is cancelled or failed immediately and no slot is consumed at higher levels. This prevents a flow-level quota breach from also counting against shared namespace or tenant limits.

Flow-level examples

The flow below defines two quotas: a short-window limit of 10 executions per hour and a longer-window limit of 100 executions per day. Executions that exceed either limit are cancelled immediately.

id: quotas_flow
namespace: company.team

quotas:
  - behavior: CANCEL
    limit: 10
    duration: PT1H

  - behavior: CANCEL
    limit: 100
    duration: P1D

tasks:
  - id: hello
    type: io.kestra.plugin.core.log.Log
    message: Hello World!

You can mix behaviors across quotas in the same flow, for example cancel executions that exceed the hourly limit but fail those that exceed the daily limit:

quotas:
  - behavior: CANCEL
    limit: 10
    duration: PT1H

  - behavior: FAIL
    limit: 100
    duration: P1D

Each duration value must be unique within the quotas list. Defining two quotas with the same duration string causes a validation error at save time.

Monitoring quota state

The Quota Limits page (left sidebar, under Tenant) lists active quota counters across the tenant. Each row shows the namespace, flow ID, quota duration, the start of the current window, and the current execution count. The Actions column contains a reset button to manually clear a quota counter before the window expires.

For namespace-level quotas, the flow column shows <namespace level quota>; for tenant-level quotas, both columns show <tenant level quota>.

Rows for expired windows are automatically hidden. Use the refresh button (top right of the page) to reload the current state. Columns are sortable by namespace and flow ID.

When to use quotas

• Flow level — cap how often a specific flow can be triggered by external events or webhooks to prevent runaway execution chains, or enforce a cost policy on flows that call expensive external APIs.
• Namespace level — apply a shared execution budget across all flows in a team or environment namespace, without configuring each flow individually.
• Tenant level — enforce an organization-wide ceiling on execution creation, for example to stay within an infrastructure or cost constraint that applies across all namespaces.
• Complement concurrency — quotas cap the creation rate; concurrency caps simultaneous parallelism.