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...');
}