start

Start/enqueue a new workflow run.

import { start } from "workflow/api";
import { myWorkflow } from "./workflows/my-workflow";

const run = await start(myWorkflow);

API Signature

Parameters

This function has multiple signatures.

Signature 1

Name	Type	Description
`workflow`	WorkflowFunction<unknown[], unknown> \| WorkflowMetadata	The imported workflow function to start.
`args`	unknown[]	The arguments to pass to the workflow (optional).
`options`	StartOptionsWithDeploymentId	The options for the workflow run (optional).

Signature 2

Name	Type	Description
`workflow`	WorkflowFunction<unknown[], unknown> \| WorkflowMetadata
`options`	StartOptionsWithDeploymentId

Signature 3

Name	Type	Description
`workflow`	WorkflowMetadata \| WorkflowFunction<TArgs, TResult>
`args`	TArgs
`options`	StartOptionsWithoutDeploymentId

Signature 4

Name	Type	Description
`workflow`	WorkflowMetadata \| WorkflowFunction<[], TResult>
`options`	StartOptionsWithoutDeploymentId

StartOptions

Name	Type	Description
`deploymentId`	"latest" \| (string & {}) \| undefined	The deployment ID to use for the workflow run. Set to `'latest'` to automatically resolve the most recent deployment for the current environment (same production target or git branch). Requires a World that implements `resolveLatestDeploymentId()`. Deprecated: This property should not be set in user code under normal circumstances. It is automatically inferred from environment variables when deploying to Vercel. Only set this if you are doing something advanced and know what you are doing. Note: When `deploymentId` is provided, the argument and return types become `unknown` since there is no guarantee the types will be consistent across deployments.
`world`	World	The world to use for the workflow run creation, by default the world is inferred from the environment variables.
`specVersion`	number	The spec version to use for the workflow run. Defaults to the latest version.

Returns

Returns a Run object:

Name	Type	Description
`runId`	string	The ID of the workflow run.
`wakeUp`	(options?: StopSleepOptions \| undefined) => Promise<StopSleepResult>	Interrupts pending `sleep()` calls, resuming the workflow early.
`cancel`	() => Promise<void>	Cancels the workflow run.
`exists`	Promise<boolean>	Whether the workflow run exists.
`status`	Promise<"pending" \| "running" \| "completed" \| "failed" \| "cancelled">	The status of the workflow run.
`returnValue`	Promise<TResult>	The return value of the workflow run. Polls the workflow return value until it is completed.
`workflowName`	Promise<string>	The name of the workflow.
`createdAt`	Promise<Date>	The timestamp when the workflow run was created.
`startedAt`	Promise<Date \| undefined>	The timestamp when the workflow run started execution. Returns undefined if the workflow has not started yet.
`completedAt`	Promise<Date \| undefined>	The timestamp when the workflow run completed. Returns undefined if the workflow has not completed yet.
`readable`	ReadableStream<any>	The readable stream of the workflow run.
`getReadable`	<R = any>(options?: WorkflowReadableStreamOptions \| undefined) => ReadableStream<R>	Retrieves the workflow run's default readable stream, which reads chunks written to the corresponding writable stream getWritable .

Learn more about WorkflowReadableStreamOptions.

Good to Know

The start() function is used in runtime/non-workflow contexts to programmatically trigger workflow executions.
This is different from calling workflow functions directly, which is the typical pattern in Next.js applications.
The function returns immediately after enqueuing the workflow - it doesn't wait for the workflow to complete.
All arguments must be serializable.
When deploymentId is provided, the argument types and return type become unknown since there is no guarantee the workflow function's types will be consistent across different deployments.

Examples

With Arguments

import { start } from "workflow/api";
import { userSignupWorkflow } from "./workflows/user-signup";

const run = await start(userSignupWorkflow, ["user@example.com"]);

With `StartOptions`

import { start } from "workflow/api";
import { myWorkflow } from "./workflows/my-workflow";

const run = await start(myWorkflow, ["arg1", "arg2"], { 
  deploymentId: "custom-deployment-id"
});

start

Signature 1

Signature 2

Signature 3

Signature 4

On this page