AWS Step Functions limits and quotas
Every state's input and output in Step Functions is limited to 256 KiB of UTF-8 text, for both Standard and Express workflows. A Standard execution can run for up to one year and record at most 25,000 events in its history before it fails; Express executions are limited to 5 minutes but have no history limit. State machine definitions are capped at 1 MB, and an account can have 1,000,000 open Standard executions per Region. The execution quotas are hard limits.
Execution limits
| Limit | Standard | Express |
|---|---|---|
| Maximum execution time | 1 year | 5 minutes |
| Execution history | 25,000 events | Unlimited (not stored by Step Functions) |
| Input or output per task, state or execution | 256 KiB | 256 KiB |
| Execution history retention after close | 90 days (can be reduced to 30) | Only via CloudWatch Logs |
| Redrive window after failure | 14 days | Not supported |
These are fixed. Hitting the payload limit fails the state with States.DataLimitExceeded; reaching the history limit fails the whole execution. A workflow exceeding its maximum time fails with States.Timeout and emits the ExecutionsTimedOut metric; see States.Timeout.
Account quotas
| Quota | Default | Can be increased to |
|---|---|---|
| Registered state machines | 100,000 | 150,000 |
| Registered activities | 100,000 | 150,000 |
| Open Standard executions per account per Region | 1,000,000 | Millions |
| Open Map Runs | 1,000 | Hard limit |
| State machine definition size | 1 MB | Hard limit |
| API request size | 1 MB | Hard limit |
| Published versions per state machine | 1,000 | Via Support |
| Aliases per state machine | 100 | Via Support |
| Name length (state machines, executions, activities) | 80 characters | Hard limit |
Starting an execution beyond the open-execution quota returns ExecutionLimitExceeded. API calls such as StartExecution are also throttled with token buckets that differ by Region; throttled calls return ThrottlingException and should be retried with backoff.
Staying under 256 KiB
The limit applies to the JSON passed between states, including whatever a Lambda function or service integration returns. Typical culprits are full API responses (an entire DescribeInstances result), large arrays fed into a Map state, and accumulating results with ResultPath so the state grows at every step.
- Store large data in S3 and pass only the bucket and key; read it in the next task.
- Trim outputs with
ResultSelector,OutputPathor JSONata output expressions so only the fields you need move on. - Use Distributed Map to iterate over items stored in S3 instead of putting a large array in the state.
- Avoid accumulation: write per-item results somewhere external rather than appending them to the state object.
Staying under 25,000 history events
Every state transition adds several events (entered, scheduled, started, succeeded, exited), so a loop of a few thousand iterations can reach 25,000 quickly. An inline Map over thousands of items does it too.
- Use Distributed Map, which runs child workflow executions with their own histories.
- For long loops, start a new execution of the same state machine from within the workflow (continue-as-new) once a counter reaches a safe threshold, passing the current position as input.
- Move very high-volume, short-lived work to Express workflows, which don't keep a history in Step Functions.
Check open executions
aws stepfunctions list-executions --state-machine-arn arn:aws:states:eu-west-2:123456789012:stateMachine:orders \
--status-filter RUNNING --query 'length(executions)'
aws service-quotas list-service-quotas --service-code states --query "Quotas[].[QuotaName,Value]" --output tableQuestions
What is the maximum payload size in Step Functions?
256 KiB per task, state or execution input or output, for both Standard and Express workflows. Pass larger data through S3.
How long can a Step Functions workflow run?
A Standard workflow can run for up to one year; an Express workflow for up to five minutes.
What happens when a Step Functions execution reaches 25,000 history events?
The execution fails. Restructure long loops with Distributed Map or by starting a fresh execution that continues from the current position.
A workflow that dies on its 25,000th event usually does it hours into a long batch run. CloudConsole, a phone app for AWS, is being built to show failed-execution alarms on your phone so you see that straight away.
About the app → · Download on the App Store