---
title: Workflow Composition
description: Call workflows from other workflows by direct await (flatten into the parent) or background spawn via start() (separate run).
type: guide
summary: Compose workflows two ways — direct await flattens the child into the parent's event log, while background spawn via start() runs the child as an independent run.
related:
  - /cookbook/advanced/child-workflows
  - /docs/api-reference/workflow-api/start
  - /docs/api-reference/workflow-api/get-run
---

# Workflow Composition



Workflows can call other workflows. Choose between two composition modes depending on whether the parent needs the child's result inline (direct await) or wants to fire the child off as an independent run (background spawn). For massive fan-out with polling and partial-failure handling, see [Child Workflows](/cookbook/advanced/child-workflows).

## When to use this

* **Direct await** — the parent needs the child's result before continuing, and you want a single unified event log
* **Background spawn** — the parent doesn't need to wait, and you want the child to be observable as a separate run with its own `runId`

## Pattern

### Direct await (flattening)

Call a child workflow with `await` and the child's steps execute inline within the parent — they appear in the parent's event log as if you'd called them directly.

```typescript lineNumbers
declare function sendEmail(userId: string): Promise<void>; // @setup
declare function sendPushNotification(userId: string): Promise<void>; // @setup
declare function createAccount(userId: string): Promise<void>; // @setup
declare function setupPreferences(userId: string): Promise<void>; // @setup

// Child workflow
export async function sendNotifications(userId: string) {
  "use workflow";

  await sendEmail(userId);
  await sendPushNotification(userId);
  return { notified: true };
}

// Parent workflow calls the child directly
export async function onboardUser(userId: string) {
  "use workflow";

  await createAccount(userId);
  await sendNotifications(userId); // [!code highlight]
  await setupPreferences(userId);

  return { userId, status: "onboarded" };
}
```

The parent waits for the child to finish before continuing. Both functions share a single workflow run, a single retry boundary, and a single event log.

### Background spawn via `start()`

To run a child workflow independently without blocking the parent, call [`start()`](/docs/api-reference/workflow-api/start) from a step. This launches the child as a separate workflow run with its own `runId`.

```typescript lineNumbers
import { start } from "workflow/api";

declare function generateReport(reportId: string): Promise<void>; // @setup
declare function fulfillOrder(orderId: string): Promise<{ id: string }>; // @setup
declare function sendConfirmation(orderId: string): Promise<void>; // @setup

async function triggerReportGeneration(reportId: string) {
  "use step"; // [!code highlight]

  const run = await start(generateReport, [reportId]); // [!code highlight]
  return run.runId;
}

export async function processOrder(orderId: string) {
  "use workflow";

  const order = await fulfillOrder(orderId);

  const reportRunId = await triggerReportGeneration(orderId); // [!code highlight]

  await sendConfirmation(orderId);

  return { orderId, reportRunId };
}
```

The parent continues immediately after `start()` returns. The child runs independently and can be monitored separately using the returned `runId` (e.g., via [`getRun()`](/docs/api-reference/workflow-api/get-run)).

<Callout type="info">
  If you want the child workflow to run on the latest deployment rather than the current one, pass [`deploymentId: "latest"`](/docs/api-reference/workflow-api/start#using-deploymentid-latest) in the `start()` options. This is currently a Vercel-specific feature. Be aware that the child workflow's function name, file path, argument types, and return type must remain compatible across deployments — renaming the function or changing its location will change the workflow ID, and modifying expected inputs or outputs can cause serialization failures.
</Callout>

## How it works

1. **Direct await flattens.** When a workflow function awaits another workflow function, the child's `"use workflow"` directive is treated as inline — the child's steps emit into the parent's event log and share the parent's run ID.
2. **`start()` mints a new run.** The child gets its own `runId`, its own event log, and its own retry boundary. The parent only sees the `runId` returned by `start()`.
3. **`start()` must be called from a step.** Calling `start()` directly from a workflow function is not allowed — wrap it in a `"use step"` function. This keeps the spawn deterministic across replays.

## Choosing between the two modes

|                            | Direct await                             | Background spawn (`start()`)               |
| -------------------------- | ---------------------------------------- | ------------------------------------------ |
| Parent waits for child     | Yes                                      | No                                         |
| Has its own `runId`        | No (shares parent's)                     | Yes                                        |
| Has its own event log      | No                                       | Yes                                        |
| Has its own retry boundary | No                                       | Yes                                        |
| Best for                   | Sequential composition, helper workflows | Independent work, fire-and-forget, fan-out |

## Adapting to your use case

* **Spawn many children at once** — call `start()` in a loop inside a step. For more advanced fan-out (chunking, polling, partial-failure handling), graduate to the [Child Workflows](/cookbook/advanced/child-workflows) recipe.
* **Wait for a background child to finish** — combine `start()` with `getRun()` polling. The [Child Workflows](/cookbook/advanced/child-workflows) page covers the full polling loop.
* **Pass results back from background children** — the spawn step returns the `runId`; later, a poll step uses `getRun(runId).returnValue` to fetch the final result.

## Key APIs

* [`"use workflow"`](/docs/foundations/workflows-and-steps) — marks the orchestrator function
* [`"use step"`](/docs/foundations/workflows-and-steps) — marks functions with full Node.js access
* [`start()`](/docs/api-reference/workflow-api/start) — spawn a child workflow as a separate run
* [`getRun()`](/docs/api-reference/workflow-api/get-run) — retrieve a workflow run's status and return value


## Sitemap
[Overview of all docs pages](/sitemap.md)