getRun

Retrieves the workflow run metadata and status information for a given run ID. This function provides immediate access to workflow run details without waiting for completion, making it ideal for status checking and monitoring.

Use this function when you need to check workflow status, get timing information, or access workflow metadata without blocking on workflow completion.

import { getRun } from "workflow/api";

const run = getRun("my-run-id");

API Signature

Parameters

Name	Type	Description
`runId`	string	The workflow run ID obtained from start.

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.
`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 .

WorkflowReadableStreamOptions

Name	Type	Description
`namespace`	string	An optional namespace to distinguish between multiple streams associated with the same workflow run.
`startIndex`	number	The index number of the starting chunk to begin reading the stream from.
`ops`	Promise<any>[]	Any asynchronous operations that need to be performed before the execution environment is paused / terminated (i.e. using `waitUntil()` or similar).
`global`	Record<string, any>	The global object to use for hydrating types from the global scope. Defaults to `globalThis`.

StopSleepOptions

Name	Type	Description
`correlationIds`	string[]	Optional list of specific correlation IDs to target. If provided, only these sleep calls will be interrupted. If not provided, all pending sleep calls will be interrupted.

StopSleepResult

Name	Type	Description
`stoppedCount`	number	Number of pending sleeps that were stopped

Examples

Basic Status Check

Check the current status of a workflow run:

import { getRun } from "workflow/api";

export async function GET(req: Request) {
  const url = new URL(req.url);
  const runId = url.searchParams.get("runId");

  if (!runId) {
    return Response.json({ error: "No runId provided" }, { status: 400 });
  }

  try {
    const run = getRun(runId); 
    const status = await run.status;

    return Response.json({ status });
  } catch (error) {
    return Response.json(
      { error: "Workflow run not found" },
      { status: 404 }
    );
  }
}

Wake Up a Sleeping Workflow

Interrupt pending sleep() calls to resume a workflow early. This is useful for testing workflows or building custom UIs that let users skip wait periods:

import { getRun } from "workflow/api";

export async function POST(req: Request) {
  const { runId } = await req.json();
  const run = getRun(runId);

  // Wake up all pending sleep calls
  const { stoppedCount } = await run.wakeUp(); 

  return Response.json({ stoppedCount });
}

You can also target specific sleep calls by correlation ID:

const run = getRun("my-run-id"); // @setup
const { stoppedCount } = await run.wakeUp({
  correlationIds: ["wait_abc123"],
});

start() - Start a new workflow and get its run ID.

getRun

On this page