start
Start and enqueue a new workflow run.
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<TArgs, TResult> | WorkflowMetadata | The imported workflow function to start. |
args | TArgs | The arguments to pass to the workflow (optional). |
options | StartOptions | The options for the workflow run (optional). |
Signature 2
| Name | Type | Description |
|---|---|---|
workflow | WorkflowMetadata | WorkflowFunction<[], TResult> | |
options | StartOptions |
StartOptions
| Name | Type | Description |
|---|---|---|
deploymentId | "latest" | (string & {}) | The deployment ID to use for the workflow run.
By default, this is automatically inferred from environment variables
when deploying to Vercel.
Set to 'latest' to automatically resolve the most recent deployment
for the current environment (same production target or git branch).
This is currently a Vercel-specific feature. |
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.
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"
}); Using deploymentId: "latest"
Set deploymentId to "latest" to automatically resolve the most recent deployment for the current environment. This is useful when you want to ensure a workflow run targets the latest deployed version of your application rather than the deployment that initiated the call.
import { start } from "workflow/api";
import { myWorkflow } from "./workflows/my-workflow";
const run = await start(myWorkflow, ["arg1", "arg2"], {
deploymentId: "latest"
}); The deploymentId option is currently a Vercel-specific feature. The "latest" value resolves to the most recent deployment matching your current environment — the same production target for production deployments, or the same git branch for preview deployments.
When using deploymentId: "latest", the workflow run will execute on a potentially different deployment than the one calling start(). Be mindful of forward and backward compatibility:
- Workflow identity: The workflow ID is derived from the function name and file path. If the latest deployment has renamed the workflow function or moved it to a different directory, the workflow ID will no longer match and the run will fail to start.
- Input and output compatibility: The arguments passed to
start()are serialized by the calling deployment but deserialized by the target deployment. Similarly, the workflow's return value is serialized by the target deployment but deserialized by the caller. If the workflow's expected arguments or return type have changed (e.g. added required fields, removed fields, or changed types), the run may fail or behave unexpectedly. Ensure that input and output schemas remain backward-compatible across deployments.