workflow/docs/api-reference/workflow-api/get-run.mdx

Workflow SDK - Build durable, resilient, and observable workflows

---
title: getRun
description: Retrieve workflow run metadata and status without waiting for completion.
type: reference
summary: Use getRun to check a workflow run's status and metadata without blocking on completion.
prerequisites:
  - /docs/foundations/starting-workflows
related:
  - /docs/foundations/idempotency
---

Retrieves workflow run metadata and status information for a given run ID. This function provides immediate access to workflow run details without waiting for completion.

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

<Callout type="info">
`getRun()` retrieves a run when you already have its `runId`. It does not look up runs by a business key. For retried requests that should route to one active workflow, use a deterministic hook token and [`getHookByToken()`](/docs/api-reference/workflow-api/get-hook-by-token). After a hook conflict, `HookConflictError.conflictingRunId` can be passed to `getRun()` to inspect, stream, or return the active owner. See [Run idempotency](/docs/foundations/idempotency#run-idempotency).
</Callout>

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

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

## API signature

### Parameters

<TSDoc
definition={`
import { getRun } from "workflow/api";
export default getRun;`}
showSections={["parameters"]}
/>

### Returns

Returns a `Run` object:

<TSDoc
definition={`
import { Run } from "workflow/api";
export default Run;`}
showSections={["returns"]}
/>

#### WorkflowReadableStream

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

<TSDoc
definition={`
import type { WorkflowReadableStream } from "workflow/api";
export default WorkflowReadableStream;`}
/>

`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](/docs/ai/resumable-streams) that need to inform clients where the stream starts.

#### WorkflowReadableStreamOptions

<TSDoc
definition={`
import type { WorkflowReadableStreamOptions } from "workflow/api";
export default WorkflowReadableStreamOptions;`}
/>

#### WorkflowRunWritableStreamOptions

<TSDoc
definition={`
import type { WorkflowRunWritableStreamOptions } from "workflow/api";
export default WorkflowRunWritableStreamOptions;`}
/>

Use `run.writable` for the default stream or `run.getWritable(options)` to configure it. See [Writing to another run's stream](/docs/foundations/streaming#writing-to-another-runs-stream) for lifecycle details.

#### StopSleepOptions

<TSDoc
definition={`
import type { StopSleepOptions } from "workflow/api";
export default StopSleepOptions;`}
/>

#### StopSleepResult

<TSDoc
definition={`
import type { StopSleepResult } from "workflow/api";
export default StopSleepResult;`}
/>

## 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:

```typescript lineNumbers
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)) { // [!code highlight]
    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:

```typescript lineNumbers
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); // [!code highlight]
    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:

```typescript lineNumbers
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(); // [!code highlight]

  return Response.json({ stoppedCount });
}
```

You can also target specific sleep calls by correlation ID:

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

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

### Cancel a run

Cancel a workflow run. You can pass an optional free-text `cancelReason` (up to 512 characters) that is recorded on the run's cancellation event and shown in the run detail view:

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

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

  await run.cancel({ cancelReason: "Superseded by a newer submission" }); // [!code highlight]

  return Response.json({ cancelled: true });
}
```

The options object is optional: `await run.cancel()` cancels the run without recording a reason.

## Related functions

- [`start()`](/docs/api-reference/workflow-api/start): Start a new workflow and get its run ID.