`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.
`cancel`	() => Promise<void>	Cancels the workflow run.
`status`	Promise<"pending" \| "running" \| "completed" \| "failed" \| "paused" \| "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 .

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

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