> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/vercel/workflow/llms.txt
> Use this file to discover all available pages before exploring further.

# getRun

> Retrieve and interact with workflow run instances

## Overview

`getRun()` retrieves a `Run` object for an existing workflow execution, allowing you to check status, read results, access streams, and control execution.

## Usage

```typescript theme={null}
import { getRun } from 'workflow/runtime';

const run = getRun('wrun_123');
const status = await run.status;
```

## Signature

```typescript theme={null}
function getRun<TResult>(runId: string): Run<TResult>
```

<ParamField path="runId" type="string" required>
  The workflow run ID (format: `wrun_{ulid}`)
</ParamField>

**Returns:** `Run<TResult>` - A Run instance for interacting with the workflow

## Run Class

The `Run` class provides methods and properties for workflow interaction:

### Properties

<ResponseField name="runId" type="string">
  The unique identifier for this workflow run
</ResponseField>

<ResponseField name="status" type="Promise<WorkflowRunStatus>">
  Current status: `'pending'`, `'running'`, `'completed'`, `'failed'`, or `'cancelled'`
</ResponseField>

<ResponseField name="returnValue" type="Promise<TResult>">
  The workflow's return value. Polls until completion.

  Throws:

  * `WorkflowRunFailedError` if the workflow failed
  * `WorkflowRunCancelledError` if the workflow was cancelled
</ResponseField>

<ResponseField name="workflowName" type="Promise<string>">
  The name of the workflow function
</ResponseField>

<ResponseField name="createdAt" type="Promise<Date>">
  Timestamp when the workflow run was created
</ResponseField>

<ResponseField name="startedAt" type="Promise<Date | undefined>">
  Timestamp when execution started, or `undefined` if not started yet
</ResponseField>

<ResponseField name="completedAt" type="Promise<Date | undefined>">
  Timestamp when execution completed, or `undefined` if not completed yet
</ResponseField>

<ResponseField name="readable" type="ReadableStream">
  The default readable stream for this workflow. Reads chunks written via `getWritable()`.
</ResponseField>

### Methods

#### getReadable()

Get a readable stream for this workflow run.

```typescript theme={null}
run.getReadable<R>(options?: WorkflowReadableStreamOptions): ReadableStream<R>
```

<ParamField path="options" type="WorkflowReadableStreamOptions">
  <Expandable title="properties">
    <ParamField path="namespace" type="string">
      Stream namespace to distinguish multiple streams
    </ParamField>

    <ParamField path="startIndex" type="number">
      Starting chunk index (0-based)
    </ParamField>

    <ParamField path="ops" type="Promise<any>[]">
      Operations to complete before environment termination
    </ParamField>

    <ParamField path="global" type="Record<string, any>">
      Global object for hydrating types (defaults to `globalThis`)
    </ParamField>
  </Expandable>
</ParamField>

#### wakeUp()

Interrupt pending `sleep()` calls. See [Run.wakeUp()](/api-reference/workflow-api/resume-hook).

```typescript theme={null}
run.wakeUp(options?: StopSleepOptions): Promise<StopSleepResult>
```

#### cancel()

Cancel the workflow execution.

```typescript theme={null}
run.cancel(): Promise<void>
```

## Examples

### Check Status

```typescript theme={null}
import { getRun } from 'workflow/runtime';

const run = getRun('wrun_123');
const status = await run.status;

switch (status) {
  case 'pending':
    console.log('Workflow queued but not started');
    break;
  case 'running':
    console.log('Workflow executing');
    break;
  case 'completed':
    console.log('Workflow finished successfully');
    break;
  case 'failed':
    console.log('Workflow encountered an error');
    break;
  case 'cancelled':
    console.log('Workflow was cancelled');
    break;
}
```

### Get Return Value

```typescript theme={null}
import { getRun } from 'workflow/runtime';
import { 
  WorkflowRunFailedError,
  WorkflowRunCancelledError 
} from '@workflow/errors';

const run = getRun('wrun_123');

try {
  const result = await run.returnValue;
  console.log('Workflow result:', result);
} catch (error) {
  if (WorkflowRunFailedError.is(error)) {
    console.error('Workflow failed:', error.message);
    console.error('Run ID:', error.runId);
  } else if (WorkflowRunCancelledError.is(error)) {
    console.log('Workflow was cancelled');
  }
}
```

### Stream Results

```typescript theme={null}
import { getRun } from 'workflow/runtime';

const run = getRun('wrun_123');
const reader = run.readable.getReader();

try {
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    console.log('Received:', value);
  }
} finally {
  reader.releaseLock();
}
```

### Multiple Streams

```typescript theme={null}
import { getRun } from 'workflow/runtime';

const run = getRun('wrun_123');

// Read from different stream namespaces
const progressStream = run.getReadable({ namespace: 'progress' });
const logsStream = run.getReadable({ namespace: 'logs' });

// Process streams independently
const progressReader = progressStream.getReader();
const logsReader = logsStream.getReader();
```

### Cancel Workflow

```typescript theme={null}
import { getRun } from 'workflow/runtime';

const run = getRun('wrun_123');

// Cancel the workflow
await run.cancel();

const status = await run.status;
console.log(status); // 'cancelled'
```

### Workflow Metadata

```typescript theme={null}
import { getRun } from 'workflow/runtime';

const run = getRun('wrun_123');

const [name, created, started, completed] = await Promise.all([
  run.workflowName,
  run.createdAt,
  run.startedAt,
  run.completedAt,
]);

console.log('Workflow:', name);
console.log('Created:', created);
console.log('Started:', started);
console.log('Completed:', completed);

if (started && completed) {
  const duration = completed.getTime() - started.getTime();
  console.log('Duration:', duration, 'ms');
}
```

### Resume from Stream Position

```typescript theme={null}
import { getRun } from 'workflow/runtime';

const run = getRun('wrun_123');

// Start reading from chunk 100
const stream = run.getReadable({ startIndex: 100 });
const reader = stream.getReader();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  processChunk(value);
}
```

### API Route Handler

```typescript theme={null}
// app/api/workflow/[runId]/route.ts
import { getRun } from 'workflow/runtime';

export async function GET(
  request: Request,
  { params }: { params: { runId: string } }
) {
  const run = getRun(params.runId);
  
  const [status, name, createdAt] = await Promise.all([
    run.status,
    run.workflowName,
    run.createdAt,
  ]);
  
  return Response.json({
    runId: run.runId,
    status,
    workflowName: name,
    createdAt,
  });
}
```

### Streaming Response

```typescript theme={null}
// app/api/workflow/[runId]/stream/route.ts
import { getRun } from 'workflow/runtime';

export async function GET(
  request: Request,
  { params }: { params: { runId: string } }
) {
  const run = getRun(params.runId);
  
  // Pipe workflow stream to response
  return new Response(run.readable, {
    headers: {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      'Connection': 'keep-alive',
    },
  });
}
```

### Poll for Completion

```typescript theme={null}
import { getRun } from 'workflow/runtime';

const run = getRun('wrun_123');

// Poll every second until completed
while (true) {
  const status = await run.status;
  
  if (status === 'completed' || status === 'failed' || status === 'cancelled') {
    break;
  }
  
  await new Promise(resolve => setTimeout(resolve, 1000));
}

console.log('Workflow finished');
```

## Error Handling

### WorkflowRunFailedError

```typescript theme={null}
import { getRun } from 'workflow/runtime';
import { WorkflowRunFailedError } from '@workflow/errors';

const run = getRun('wrun_123');

try {
  const result = await run.returnValue;
} catch (error) {
  if (WorkflowRunFailedError.is(error)) {
    console.error('Workflow failed');
    console.error('Run ID:', error.runId);
    console.error('Error:', error.workflowError?.message);
    console.error('Stack:', error.workflowError?.stack);
  }
}
```

### WorkflowRunCancelledError

```typescript theme={null}
import { getRun } from 'workflow/runtime';
import { WorkflowRunCancelledError } from '@workflow/errors';

const run = getRun('wrun_123');

try {
  const result = await run.returnValue;
} catch (error) {
  if (WorkflowRunCancelledError.is(error)) {
    console.log('Workflow was cancelled');
    console.log('Run ID:', error.runId);
  }
}
```

### WorkflowRunNotFoundError

```typescript theme={null}
import { getRun } from 'workflow/runtime';
import { WorkflowRunNotFoundError } from '@workflow/errors';

const run = getRun('wrun_invalid');

try {
  const status = await run.status;
} catch (error) {
  if (WorkflowRunNotFoundError.is(error)) {
    console.error('Run not found:', error.runId);
  }
}
```

## Type Safety

```typescript theme={null}
import { getRun } from 'workflow/runtime';

// Define workflow return type
interface WorkflowResult {
  success: boolean;
  data: string[];
}

// Type-safe run instance
const run = getRun<WorkflowResult>('wrun_123');

// Return value is typed
const result = await run.returnValue;
console.log(result.success); // ✓ TypeScript knows the shape
console.log(result.data);    // ✓ Typed as string[]
```

## Best Practices

1. **Type the result**: Use `getRun<TResult>()` for type-safe return values

2. **Handle all error cases**: Check for failed, cancelled, and not-found errors

3. **Use streams for real-time updates**: Don't poll status, use streams instead

4. **Store run IDs**: Persist run IDs in your database for later retrieval

5. **Check status before actions**: Verify workflow state before cancel/wakeUp operations

6. **Clean up readers**: Always release stream readers when done

## See Also

* [start()](/api-reference/workflow-api/start-workflow)
* [Run.wakeUp()](/api-reference/workflow-api/resume-hook)
* [getWritable()](/api-reference/core/writable-stream)
* [Error Types](/essentials/error-handling)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.