Operation memory
Pulse State
Pulse State helps trusted backend code remember protected operation keys long enough to prevent duplicate work.
Pulse State guide for idempotency, duplicate protection, and operation retention.
Implementation focus
Use this when a webhook, schedule, retry, or form submission must run once per event instead of once per request attempt.
Expected outcomes
- Use `runOnce()` for duplicate-safe work.
- Pick stable keys and retention windows.
- Understand replay limits and quota behavior.
- Choose a real data surface when the job is app storage.
Pulse State remembers operations
Pulse State is small, platform-managed memory for operation keys. It helps a Pulse decide whether a protected operation is already running, completed, failed, or safe to retry. It is meant for idempotency and duplicate protection, not general app storage.
Use it when repeated calls need to agree on the same protected operation: verified webhook event ids, scheduled window keys, form idempotency tokens, or provider event ids that must run once.
- Verify webhooks before deriving the Pulse State key.
- Only awaited work inside `runOnce()` is protected.
- Completed duplicates can replay a small JSON-safe result when replay is available.
- Creator code cannot list, delete, purge, or reset Pulse State records.
Retention and quotas
Pulse State retention is capped by plan and by the operation's requested retention. Retention keeps duplicate memory alive across cold starts, but it is not an archive, database, or long-term analytics store.
High-cardinality keys can consume quota quickly. Choose keys that represent real protected operations, not noisy browser events, random timestamps, or user input that changes on every retry.
- Use `runOnce()` for the common case.
- Use manual claim lifecycle only when a workflow needs explicit accepted, completed, or failed transitions.
- Reduce retention when duplicate protection only needs a short window.
- Use `env.db` or an external service for durable app records.
Example and read next
Example: a webhook provider retries the same event. Verify the signature, derive a stable event key, wrap awaited side effects in runOnce, and keep retention just long enough to block duplicates.
Use these related pages when you need the next layer of guidance. They point to the most likely follow-up tasks, not every page that happens to touch the same system.
- Read next: Pulse Runtime API
- Read next: Automation Safety
- Read next: Data Surfaces
- Read next: Calling Pulses