Docs / Scripts
How runs share capacity
Every event that starts a script becomes a run. Runs wait in a queue and run in slots. Two settings on a script decide how many of its runs may be active at once; everything else is the platform’s fairness. The settings are described in Triggers and concurrency; what bounds the queue is in Limits and safety.
| Setting | Where | What it decides | Without it |
|---|---|---|---|
maxConcurrency | script | How many runs of this script may be active at once | one at a time |
concurrencyKey | script | A name several scripts share, so they share one limit | the script’s own name |
A run keeps the limit it started under, even if the script is changed while it is parked.
Slots and the queue
1A runtime has a fixed number of slots. A slot is reserved before the next event is taken from the queue, so waiting work stays in the queue, not in memory.
2When every slot is busy, new events wait in the queue. They are accepted, not refused, while the queue has room.
3When a run finishes, its slot takes the next event at once.
One script’s limit
1Two runs of the script are active, which is its limit. Without a setting the limit is one run at a time per script and environment.
2A third event arrives at the limit. It is set aside in the queue: it keeps its place and uses no delivery attempt. It is never refused for this reason.
3One run finishes; the waiting event starts as the second active run.
A limit shared by key
1Two scripts that touch the same system name the same concurrencyKey. They now share one limit — here, one run at a time.
2An invoices run waits while the orders run holds the key, although it belongs to another script.
3When the orders run ends, the invoices run starts. The limit that applies is the one of the script that is starting.
Fair turns
1One tenant has a large backlog, another a little work.
2Turns go round the tenants: each gets a few, then the next one. The small tenant's work does not wait for the large backlog.
3Inside a tenant every source has its own queue. Resumed runs go first, and every webhook endpoint and the schedule still get a turn in each round.
Long runs take turns
1A run computes for a long time while other work waits.
2After its share of time the run is saved and queued again. The next run gets the slot; nothing is lost and nothing is repeated.
3On its next turn the run continues exactly where it stopped.
Inside a run, one call at a time
1Inside a run, calls happen one after another, and each answer is recorded before the next call starts. A script has no parallel branches.
2Work happens at the same time across runs: each event starts its own run, each in its own slot and within the script's maxConcurrency. Bulk work over many records belongs in the dataset functions.