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.
`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`	WorkflowReadableStream<any>	The readable stream of the workflow run.
`getReadable`	<R = any>(options?: WorkflowReadableStreamOptions \| undefined) => WorkflowReadableStream<R>	Retrieves the workflow run's default readable stream, which reads chunks written to the corresponding writable stream getWritable . The returned stream has an additional WorkflowReadableStream.getTailIndex getTailIndex() helper that returns the index of the last known chunk. This is useful when building reconnection endpoints that need to inform clients where the stream starts.

WorkflowReadableStream

run.getReadable() returns a WorkflowReadableStream — a standard ReadableStream extended with a getTailIndex() helper:

Name	Type	Description
`locked`	boolean	The `locked` read-only property of the ReadableStream interface returns whether or not the readable stream is locked to a reader. MDN Reference
`cancel`	(reason?: any) => Promise<void>	The `cancel()` method of the ReadableStream interface returns a Promise that resolves when the stream is canceled. MDN Reference
`getReader`	{ (options: { mode: "byob"; }): ReadableStreamBYOBReader; (): ReadableStreamDefaultReader<R>; (options?: ReadableStreamGetReaderOptions \| undefined): ReadableStreamReader<...>; }	The `getReader()` method of the ReadableStream interface creates a reader and locks the stream to it. MDN Reference
`pipeThrough`	<T>(transform: ReadableWritablePair<T, R>, options?: StreamPipeOptions \| undefined) => ReadableStream<T>	The `pipeThrough()` method of the ReadableStream interface provides a chainable way of piping the current stream through a transform stream or any other writable/readable pair. MDN Reference
`pipeTo`	(destination: WritableStream<R>, options?: StreamPipeOptions \| undefined) => Promise<void>	The `pipeTo()` method of the ReadableStream interface pipes the current `ReadableStream` to a given WritableStream and returns a Promise that fulfills when the piping process completes successfully, or rejects if any errors were encountered. MDN Reference
`tee`	() => [ReadableStream<R>, ReadableStream<R>]	The `tee()` method of the two-element array containing the two resulting branches as new ReadableStream instances. MDN Reference
`getTailIndex`	() => Promise<number>	Returns the tail index (index of the last known chunk, 0-based) of the underlying workflow stream. Useful for resolving a negative `startIndex` into an absolute position — for example, when building reconnection endpoints that need to inform the client where the stream starts. Returns `-1` when no chunks have been written yet.

getTailIndex() returns the index of the last known chunk (0-based), or -1 when no chunks have been written. This is useful when building reconnection endpoints that need to inform clients where the stream starts.

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. Negative values start from the end (e.g. -3 reads the last 3 chunks).
`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

Check if a Run Exists

Use the exists getter to check whether a workflow run exists without throwing when the run is not found:

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

  const run = getRun(runId);

  if (!(await run.exists)) { 
    return Response.json(
      { error: "Workflow run not found" },
      { status: 404 }
    );
  }

  const status = await run.status;
  return Response.json({ status });
}

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:

import { getRun } from "workflow/api";

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