Skip to content

chore(docs): Add clarifications for delay semantics and payload handling #2928

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ericallam merged 2 commits into from
Jan 24, 2026
Merged

chore(docs): Add clarifications for delay semantics and payload handling #2928

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d892261
date object payload note
isshaddad Jan 23, 2026
3931bf8
clarification for delay sementics
isshaddad Jan 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions docs/triggering.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -707,7 +707,8 @@ Runs that are delayed and have not been enqueued yet will display in the dashboa

<Note>
Delayed runs will be enqueued at the time specified, and will run as soon as possible after that
time, just as a normally triggered run would.
time, just as a normally triggered run would. They execute on the currently deployed version when
they start, not the version that was active when they were enqueued.
</Note>

You can cancel a delayed run using the `runs.cancel` SDK function:
Expand All @@ -733,6 +734,12 @@ The `delay` option is also available when using `batchTrigger`:
await myTask.batchTrigger([{ payload: { some: "data" }, options: { delay: "1h" } }]);
```

<Note>
If your payload contains Date objects, pass them directly rather than manually stringifying with
`JSON.stringify()`. The SDK handles Date serialization automatically. If you need to stringify
manually, convert Dates to ISO strings first (e.g., `date.toISOString()`).
</Note>

### `ttl`

You can set a TTL (time to live) when triggering a task, which will automatically expire the run if it hasn't started within the specified time. This is useful for ensuring that a run doesn't get stuck in the queue for too long.
Expand Down Expand Up @@ -1048,7 +1055,7 @@ You can override the default region when you trigger a run:
await yourTask.trigger(payload, { region: "eu-central-1" });
```

If you don't specify a region it will use the default for your project. Go to the "Regions" page in the dashboard to see available regions or switch your default.
If you don't specify a region it will use the default for your project. Go to the "Regions" page in the dashboard to see available regions or switch your default. Static IP addresses are also available on the Regions page for paid plans.

The region is where your runs are executed, it does not change where the run payload, output, tags, logs, or are any other data is stored.

Expand Down
2 changes: 2 additions & 0 deletions docs/versioning.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,8 @@ Versions numbers are incremented each time a new version is created for that dat

When a task run starts it is locked to the latest version of the code (for that environment). Once locked it won't change versions, even if you deploy new versions. This is to ensure that a task run is not affected by changes to the code.

Delayed runs are locked to the version that's active when they begin executing, not when they're enqueued.

### Child tasks and version locking

Trigger and wait functions version lock child task runs to the parent task run version. This ensures the results from child runs match what the parent task is expecting. If you don't wait then version locking doesn't apply.
Expand Down