TypeScript SDK

Managing concurrency

Limit the number of concurrently running steps for your function with the concurrency configuration options. Setting an optional key parameter limits the concurrency for each unique value of the expression.

Important: Concurrency limits step execution, not the total number of function runs. Functions that are sleeping, waiting for events, or paused between steps do not count against your concurrency limit. This means you may have many more function runs in progress than your concurrency limit. Learn more about how concurrency works →

Read our concurrency guide for more information on concurrency, including how it works and any limits.

export default inngest.createFunction(
  {
    id: "sync-contacts",
    concurrency: {
      limit: 10,
    },
  }
  // ...
);

Setting concurrency limits are very useful for:

  • Handling API rate limits - Limit concurrency to stay within the rate limit quotas that are allowed by a given third party API.
  • Limiting database operations or connections
  • Preventing one of your user's accounts from consuming too many resources (see key)

Alternatively, if you want to limit the number of times that your function runs in a given period, the rateLimit option may be better for your use case.

Configuration

  • Name
    concurrency
    Type
    number | object | [object, object]
    Required
    optional
    Description

    Options to configure concurrency. Specifying a number is a shorthand to set the limit property.

    Properties
    • Name
      limit
      Type
      number
      Required
      required
      Description

      The maximum number of concurrently running steps. A value of 0 or undefined is the equivalent of not setting a limit. The maximum value is dictated by your account's plan.

    • Name
      scope
      Type
      'account' | 'env' | 'fn'
      Required
      optional
      Description

      The scope for the concurrency limit, which impacts whether concurrency is managed on an individual function, across an environment, or across your entire account.

      • fn (default): only the runs of this function affects the concurrency limit
      • env: all runs within the same environment that share the same evaluated key value will affect the concurrency limit. This requires setting a key which evaluates to a virtual queue name.
      • account: every run that shares the same evaluated key value will affect the concurrency limit, across every environment. This requires setting a key which evaluates to a virtual queue name.
    • Name
      key
      Type
      string
      Required
      optional
      Description

      An expression which evaluates to a string given the triggering event. The string returned from the expression is used as the concurrency queue name. A key is required when setting an env or account level scope.

      Expressions are defined using the Common Expression Language (CEL) with the original event accessible using dot-notation. Read our guide to writing expressions for more info. Examples:

      • Limit concurrency to n (via limit) per customer id: 'event.data.customer_id'
      • Limit concurrency to n per user, per import id: 'event.data.user_id + "-" + event.data.import_id'
      • Limit globally using a specific string: '"global-quoted-key"' (wrapped in quotes, as the expression is evaluated as a language)

Step-level concurrency: The concurrency option controls the number of concurrent steps that can be running at any one time, not the number of function runs.

Because function runs frequently pause (for sleeps, waiting for events, or between steps), it's common to have many more function runs in progress than your concurrency limit. However, only the configured number of steps will ever be actively executing at once.

For example, with concurrency: 10, you might have 500 function runs in progress, but only 10 steps are executing code at any given moment.