Debounced task runs

Debounced task runs allow you to consolidate multiple triggers into a single execution. When triggering a task with a debounce key, subsequent triggers with the same key will reschedule the existing delayed run instead of creating new runs. This continues until no new triggers occur within the delay window.

This is perfect for scenarios like:

• User activity updates: Consolidate rapid user actions into a single processing run
• Webhook deduplication: Handle bursts of webhooks without redundant processing
• Search indexing: Batch document updates instead of processing each change individually
• Notification batching: Group notifications to avoid spamming users

How it works

Usage

Options

• key: A unique identifier for the debounce group, scoped to the task identifier
• delay: How long to wait before executing (supports duration strings like "5s", "1m", or milliseconds)
• mode: Either "leading" (default) or "trailing"

Leading vs Trailing mode

Leading mode (default): Uses the payload and options from the first trigger. Subsequent triggers only push back the execution time.

Trailing mode: Uses the payload and options from the last trigger. The following options are updated from each new trigger:

• payload - The task input data
• metadata - Run metadata
• tags - Run tags (replaces existing tags)
• maxAttempts - Maximum retry attempts
• maxDuration - Maximum compute time
• machine - Machine preset (cpu/memory)

Behavior notes

• Idempotency keys take precedence: If both debounce and idempotency key are specified, idempotency is checked first
• Works with triggerAndWait: Parent runs correctly block on the debounced run.

Read the full docs for more details.