Create Function

Define your functions using the create_function decorator.

import inngest

@inngest_client.create_function(
    fn_id="import-product-images",
    trigger=inngest.TriggerEvent(event="shop/product.imported"),
)
async def fn(ctx: inngest.Context, step: inngest.Step):
    # Your function code

`create_function`

The create_function decorator accepts a configuration and wraps a plain function.

Configuration

Name
batch_events
Type
Batch
Required
optional
Description
Configure how the function should consume batches of events (reference)
- Name
  max_size
  Type
  int
  Required
  required
  Description
  The maximum number of events a batch can have. Current limit is 100.
- Name
  timeout
  Type
  int | datetime.timedelta
  Required
  required
  Description
  How long to wait before invoking the function with the batch even if it's not full. Current permitted values are between 1 second and 1 minute. If you pass an int then it'll be interpreted in milliseconds.
Name
cancel
Type
Cancel
Required
optional
Description
Define an event that can be used to cancel a running or sleeping function (guide)
- Name
  event
  Type
  str
  Required
  required
  Description
  The event name which will be used to cancel
- Name
  if_exp
  Type
  str
  Required
  optional
  Description
  A match expression using arbitrary event data. For example, event.data.user_id == async.data.user_id will only match events whose data.user_id matches the original trigger event's data.user_id.
- Name
  timeout
  Type
  int | datetime.timedelta
  Required
  optional
  Description
  The amount of time to wait to receive the cancelling event. If you pass an int then it'll be interpreted in milliseconds.
Name
debounce
Type
Debounce
Required
optional
Description
Options to configure function debounce (reference)
- Name
  key
  Type
  str
  Required
  optional
  Description
  A unique key expression to apply the debounce to. The expression is evaluated for each triggering event.
  Expressions are defined using the Common Expression Language (CEL) with the events accessible using dot-notation. Read our guide to writing expressions for more info. Examples:
  
  Debounce per customer id: 'event.data.customer_id'
  
  Debounce per account and email address: 'event.data.account_id + "-" + event.user.email'
- Name
  period
  Type
  int | datetime.timedelta
  Required
  required
  Description
  The time period of which to set the limit. The period begins when the first matching event is received. How long to wait before invoking the function with the batch even if it's not full. If you pass an int then it'll be interpreted in milliseconds.
Name
fn_id
Type
str
Required
required
Description
A unique identifier for your function. This should not change between deploys.
Name
name
Type
str
Required
optional
Description
A name for your function. If defined, this will be shown in the UI as a friendly display name instead of the ID.
Name
on_failure
Type
function
Required
optional
Description
A function that will be called only when this Inngest function fails after all retries have been attempted (reference)
Name
priority
Type
Priority
Required
optional
Version
0.4.0+
Description
Configure function run prioritization.
- Name
  run
  Type
  string
  Required
  optional
  Description
  An expression which must return an integer between -600 and 600 (by default), with higher return values resulting in a higher priority.
  Examples:
  
  Return the priority within an event directly: event.data.priority (where event.data.priority is an int within your account's range)
  
  Rate limit by a string field: event.data.plan == 'enterprise' ? 180 : 0
  
  See reference for more information.
Name
rate_limit
Type
RateLimit
Required
optional
Description
Options to configure how to rate limit function execution (reference)
- Name
  key
  Type
  str
  Required
  optional
  Description
  A unique key expression to apply the limit to. The expression is evaluated for each triggering event.
  Expressions are defined using the Common Expression Language (CEL) with the events accessible using dot-notation. Read our guide to writing expressions for more info. Examples:
  
  Rate limit per customer id: 'event.data.customer_id'
  
  Rate limit per account and email address: 'event.data.account_id + "-" + event.user.email'
- Name
  limit
  Type
  int
  Required
  required
  Description
  The maximum number of functions to run in the given time period.
- Name
  period
  Type
  int | datetime.timedelta
  Required
  required
  Description
  The time period of which to set the limit. The period begins when the first matching event is received. How long to wait before invoking the function with the batch even if it's not full. Current permitted values are from 1 second to 1 minute. If you pass an int then it'll be interpreted in milliseconds.
Name
retries
Type
int
Required
optional
Description
Configure the number of times the function will be retried from 0 to 20. Default: 4
Name
throttle
Type
Throttle
Required
optional
Description
Options to configure how to throttle function execution
- Name
  count
  Type
  int
  Required
  required
  Description
  The maximum number of functions to run in the given time period.
- Name
  key
  Type
  str
  Required
  optional
  Description
  A unique key expression to apply the limit to. The expression is evaluated for each triggering event.
  Expressions are defined using the Common Expression Language (CEL) with the events accessible using dot-notation. Read our guide to writing expressions for more info. Examples:
  
  Rate limit per customer id: 'event.data.customer_id'
  
  Rate limit per account and email address: 'event.data.account_id + "-" + event.user.email'
- Name
  period
  Type
  int | datetime.timedelta
  Required
  required
  Description
  The time period of which to set the limit. The period begins when the first matching event is received. How long to wait before invoking the function with the batch even if it's not full. Current permitted values are from 1 second to 1 minute. If you pass an int then it'll be interpreted in milliseconds.
Name
idempotency
Type
string
Required
optional
Description
A key expression used to prevent duplicate events from triggering a function more than once in 24 hours. Read the idempotency guide here.
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 information.
Name
trigger
Type
TriggerEvent | TriggerCron | list[TriggerEvent | TriggerCron]
Required
required
Description
What should trigger the function to run. Either an event or a cron schedule. Use a list to specify multiple triggers.

Triggers

`TriggerEvent`

Name
event
Type
str
Required
required
Description
The name of the event.
Name
expression
Type
str
Required
optional
Description
A match expression using arbitrary event data. For example, event.data.user_id == async.data.user_id will only match events whose data.user_id matches the original trigger event's data.user_id.

`TriggerCron`

Name
cron
Type
str
Required
required
Description
A unix-cron compatible schedule string.
Optional timezone prefix, e.g. TZ=Europe/Paris 0 12 * * 5.

Multiple Triggers

Multiple triggers can be defined by setting the trigger option to a list of TriggerEvent or TriggerCron objects:

import inngest

@inngest_client.create_function(
    fn_id="import-product-images",
    trigger=[
      inngest.TriggerEvent(event="shop/product.imported"),
      inngest.TriggerEvent(event="shop/product.updated"),
    ],
)
async def fn(ctx: inngest.Context, step: inngest.Step):
    # Your function code

For more information, see the Multiple Triggers guide.

The handler is your code that runs whenever the trigger occurs. Every function handler receives a single object argument which can be deconstructed. The key arguments are event and step. Note, that scheduled functions that use a cron trigger will not receive an event argument.

@inngest_client.create_function(
    # Function options
)
async def fn(ctx: inngest.Context, step: inngest.Step):
    # Function code

`ctx`

Name
attempt
Type
int
Description
The current zero-indexed attempt number for this function execution. The first attempt will be 0, the second 1, and so on. The attempt number is incremented every time the function throws an error and is retried.
Name
event
Type
Event
Description
The event payload object that triggered the given function run. The event payload object will match what you send with inngest.send(). Below is an example event payload object:
Properties
- Name
  data
  Type
  dict[str, object]
  Description
  The event payload data.
- Name
  id
  Type
  str
  Description
- Name
  name
  Type
  str
  Description
- Name
  ts
  Type
  int
  Description
  Time (Unix millis) the event was received by the Inngest server.
Name
events
Type
list[Event]
Description
A list of event objects that's accessible when the batch_events is set on the function configuration.
If batching is not configured, the list contains a single event payload matching the event argument.
Name
logger
Type
logging.Logger
Description
A proxy object around either the logger you provided or the default logger.
Name
run_id
Type
str
Description
The unique ID for the given function run. This can be useful for logging and looking up specific function runs in the Inngest dashboard.

`step`

The step object has a method for each kind of step in the Inngest platform.

If your function is async then its type is Step and you can use await to call its methods. If your function is not async then its type is SyncStep.

Name
run
Type
Callable
Description
Docs
Name
send_event
Type
Callable
Description
Docs
Name
sleep
Type
Callable
Description
Docs
Name
sleep_until
Type
Callable
Description
Docs
Name
_experimental_parallel
Type
Callable
Version
0.2.0+
Description
Docs

Local Development

Events & Triggers

Inngest Functions

Steps & Workflows

Flow Control

Errors & Retries

Cancellation

Middleware

Deployment

Manage

Monitor

Workflow Kit

TypeScript SDK

Python SDK

Steps

Middleware

Guides

Migrations

Go SDK

REST API

System events