TanStack
Workflow v0v0
Docs
Cloudflare
Railway
CodeRabbit
Netlify
Clerk
OpenRouter
WorkOS
AG Grid
SerpAPI
Prisma
Electric
Unkey
Sentry
Cloudflare
Railway
CodeRabbit
Netlify
Clerk
OpenRouter
WorkOS
AG Grid
SerpAPI
Prisma
Electric
Unkey
Sentry
Menu
Getting Started
Guide
Cookbook
Concepts
API Reference
API Reference

Runtime API

Runtime API

@tanstack/workflow-runtime provides the deployment-independent execution runtime.

defineWorkflowRuntime

Registers workflows and returns runtime methods.

ts
import { defineWorkflowRuntime } from '@tanstack/workflow-runtime'

const runtime = defineWorkflowRuntime({
  store,
  defaultLeaseMs: 30_000,
  workflows: {
    checkout: {
      load: async () => checkoutWorkflow,
      version: 'v2',
      previousVersions: {
        v1: async () => checkoutWorkflowV1,
      },
      schedules: [],
    },
  },
})
import { defineWorkflowRuntime } from '@tanstack/workflow-runtime'

const runtime = defineWorkflowRuntime({
  store,
  defaultLeaseMs: 30_000,
  workflows: {
    checkout: {
      load: async () => checkoutWorkflow,
      version: 'v2',
      previousVersions: {
        v1: async () => checkoutWorkflowV1,
      },
      schedules: [],
    },
  },
})

Workflow registration

FieldPurpose
loadAsync workflow loader. Can return a workflow, { default }, or { workflow }.
versionCurrent workflow version for new runs.
previousVersionsLoaders for old versions that still have paused runs.
schedulesRegistered recurring schedules for this workflow.

runtime.startRun

Starts or attaches to a run ID through the runtime store.

ts
const result = await runtime.startRun({
  workflowId: 'checkout',
  runId: 'checkout:order-1',
  input: { orderId: 'order-1' },
  leaseOwner: 'api:checkout',
  leaseMs: 30_000,
  includeEvents: false,
})
const result = await runtime.startRun({
  workflowId: 'checkout',
  runId: 'checkout:order-1',
  input: { orderId: 'order-1' },
  leaseOwner: 'api:checkout',
  leaseMs: 30_000,
  includeEvents: false,
})

Options:

OptionPurpose
workflowIdRegistered workflow key.
runIdStable run identifier.
inputWorkflow input for new runs.
nowOverride current time for tests or host events.
leaseOwnerWorker identity used while executing.
leaseMsLease duration.
threadIdOptional core engine thread ID.
includeEventsWhether to retain emitted events in the result. Defaults to true.
maxEventsMaximum retained events when includeEvents is true.

runtime.deliverSignal

Delivers an external signal and resumes the run.

ts
await runtime.deliverSignal({
  runId: 'checkout:order-1',
  signalId: 'stripe:evt_123',
  name: 'payment-received',
  payload: { paymentId: 'pi_123' },
})
await runtime.deliverSignal({
  runId: 'checkout:order-1',
  signalId: 'stripe:evt_123',
  name: 'payment-received',
  payload: { paymentId: 'pi_123' },
})

Use stable signalId values so webhook retries are idempotent.

runtime.deliverApproval

Delivers an approval decision and resumes the run.

ts
await runtime.deliverApproval({
  runId,
  approval: {
    approvalId,
    approved: true,
    feedback: 'Approved',
  },
})
await runtime.deliverApproval({
  runId,
  approval: {
    approvalId,
    approved: true,
    feedback: 'Approved',
  },
})

runtime.sweep

Claims due schedules and timers, then drives them to completion or the next pause.

ts
const result = await runtime.sweep({
  now: Date.now(),
  maxScheduledRuns: 25,
  maxTimers: 25,
  maxDurationMs: 55_000,
  leaseOwner: 'cron:sweep',
  leaseMs: 30_000,
  includeEvents: false,
})
const result = await runtime.sweep({
  now: Date.now(),
  maxScheduledRuns: 25,
  maxTimers: 25,
  maxDurationMs: 55_000,
  leaseOwner: 'cron:sweep',
  leaseMs: 30_000,
  includeEvents: false,
})

Options:

OptionPurpose
nowCurrent timestamp used for due checks.
limitBackward-compatible shared limit for schedules and timers.
maxScheduledRunsMaximum due schedule buckets to start.
maxTimersMaximum due timers to resume.
maxDurationMsWall-clock budget for this sweep.
leaseOwnerWorker identity for claimed work.
leaseMsLease duration.
includeEventsWhether to retain emitted events. Sweeps usually set false.
maxEventsMaximum retained events per run result.

Result:

ts
interface WorkflowRuntimeSweepResult {
  scheduled: ReadonlyArray<WorkflowRuntimeRunResult>
  timers: ReadonlyArray<WorkflowRuntimeRunResult>
  summary: WorkflowRuntimeSweepSummary
  deadlineReached: boolean
  remainingMayExist: boolean
}
interface WorkflowRuntimeSweepResult {
  scheduled: ReadonlyArray<WorkflowRuntimeRunResult>
  timers: ReadonlyArray<WorkflowRuntimeRunResult>
  summary: WorkflowRuntimeSweepSummary
  deadlineReached: boolean
  remainingMayExist: boolean
}

remainingMayExist means the sweep stopped at a count or time budget, so more due work may be available.

cron

Creates a cron schedule spec.

ts
import { cron } from '@tanstack/workflow-runtime'

cron('0 9 * * 1', { timezone: 'UTC' })
import { cron } from '@tanstack/workflow-runtime'

cron('0 9 * * 1', { timezone: 'UTC' })

Current materialization supports numeric five-field UTC cron schedules.

every

Creates interval schedule specs.

ts
import { every } from '@tanstack/workflow-runtime'

every.seconds(30)
every.minutes(15)
every.hours(1)
import { every } from '@tanstack/workflow-runtime'

every.seconds(30)
every.minutes(15)
every.hours(1)

materializeWorkflowSchedules

Computes due schedule buckets from registered workflow schedules.

ts
import { materializeWorkflowSchedules } from '@tanstack/workflow-runtime'

const materialized = await materializeWorkflowSchedules(runtime, {
  now: Date.now(),
  cronLookbackMs: 24 * 60 * 60 * 1000,
})
import { materializeWorkflowSchedules } from '@tanstack/workflow-runtime'

const materialized = await materializeWorkflowSchedules(runtime, {
  now: Date.now(),
  cronLookbackMs: 24 * 60 * 60 * 1000,
})

Host adapters call this for you before sweeping.

inMemoryWorkflowExecutionStore

Creates an in-memory WorkflowExecutionStore for tests and local demos.

ts
import { inMemoryWorkflowExecutionStore } from '@tanstack/workflow-runtime'

const store = inMemoryWorkflowExecutionStore()
import { inMemoryWorkflowExecutionStore } from '@tanstack/workflow-runtime'

const store = inMemoryWorkflowExecutionStore()

Do not use this as production persistence. Memory disappears when the process exits.

createRunStoreAdapter

Adapts a WorkflowExecutionStore to the core engine's RunStore interface.

Most users will not call this directly. The runtime driver uses it internally.

createRuntimeDriver

Lower-level helper used by defineWorkflowRuntime.

Most users should call defineWorkflowRuntime.

Edit on GitHub
Core API
Store Adapters
© 2026 TanStack LLC