Skip to main content

Run.startAsync()

The .startAsync() method starts a workflow run without waiting for completion. It returns immediately with the runId, allowing the workflow to execute in the background. This is useful for long-running workflows, scheduled tasks, or when you want to avoid blocking on workflow completion.

Usage example
Direct link to Usage example

const run = await workflow.createRun()

// Fire-and-forget - returns immediately
const { runId } = await run.startAsync({
  inputData: {
    value: 'initial data',
  },
})

// Optionally poll for completion later
const result = await workflow.getWorkflowRunExecutionResult(runId)

Parameters
Direct link to Parameters

inputData?:

z.infer<TInput>
Input data that matches the workflow's input schema

requestContext?:

RequestContext
Request Context data to use during workflow execution

initialState?:

z.infer<TState>
Initial state to use for the workflow execution

tracingOptions?:

TracingOptions
Options for Tracing configuration.

metadata?:

Record<string, any>
Metadata to add to the root trace span. Useful for adding custom attributes like user IDs, session IDs, or feature flags.

traceId?:

string
Trace ID to use for this execution (1-32 hexadecimal characters). If provided, this trace will be part of the specified trace.

outputOptions?:

OutputOptions
Options for output configuration.

includeState?:

boolean
Whether to include the workflow run state in the result.

Returns
Direct link to Returns

runId:

string
The unique identifier for this workflow run. Use this to check status or retrieve results later.

When to use startAsync()
Direct link to when-to-use-startasync

Use startAsync() instead of start() when:

  • Long-running workflows: The workflow may take minutes or hours to complete
  • Scheduled/cron triggers: You want to trigger a workflow without blocking the scheduler
  • Avoiding polling failures: With Inngest workflows, start() polls for completion which can fail and cause retries. startAsync() avoids this issue
  • Background processing: You want to queue work and handle results asynchronously

Checking workflow status
Direct link to Checking workflow status

After calling startAsync(), you can check the workflow status using:

// Get the execution result (including step outputs)
const result = await workflow.getWorkflowRunExecutionResult(runId)

if (result?.status === 'success') {
  console.log('Workflow completed:', result.steps)
} else if (result?.status === 'failed') {
  console.log('Workflow failed:', result.error)
} else if (result?.status === 'running') {
  console.log('Workflow still running...')
}
On this page