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

# getWorkflowMetadata

> Get metadata about the current workflow run

Returns metadata about the current workflow run, including the run ID, start time, and trigger URL.

## Signature

```typescript theme={null}
function getWorkflowMetadata(): WorkflowMetadata
```

## Returns

<ResponseField name="WorkflowMetadata" type="WorkflowMetadata">
  Metadata about the current workflow run.

  <Expandable title="properties">
    <ResponseField name="workflowRunId" type="string">
      Unique identifier for the workflow run.
    </ResponseField>

    <ResponseField name="workflowStartedAt" type="Date">
      Timestamp when the workflow run started.
    </ResponseField>

    <ResponseField name="url" type="string">
      The URL where the workflow can be triggered.
    </ResponseField>
  </Expandable>
</ResponseField>

## Usage

### Basic Usage

Get workflow metadata inside a workflow function:

```typescript theme={null}
import { getWorkflowMetadata } from 'workflow';

export async function workflowWithMetadata() {
  "use workflow";

  const metadata = getWorkflowMetadata();
  
  console.log('Run ID:', metadata.workflowRunId);
  console.log('Started at:', metadata.workflowStartedAt);
  console.log('Trigger URL:', metadata.url);
}
```

### Use in Step Functions

Access workflow metadata from within a step:

```typescript theme={null}
import { step, getWorkflowMetadata } from 'workflow';

export async function workflowWithStepMetadata() {
  "use workflow";

  await step(async () => {
    "use step";
    
    const { workflowRunId } = getWorkflowMetadata();
    
    console.log('Processing in run:', workflowRunId);
    await processData(workflowRunId);
  });
}
```

### Track Workflow Duration

Calculate how long a workflow has been running:

```typescript theme={null}
import { getWorkflowMetadata, sleep } from 'workflow';

export async function workflowWithDuration() {
  "use workflow";

  const { workflowStartedAt } = getWorkflowMetadata();
  
  await performWork();
  
  const duration = Date.now() - workflowStartedAt.getTime();
  console.log(`Workflow has been running for ${duration}ms`);
}
```

### Include Run ID in External Requests

Pass the run ID to external systems:

```typescript theme={null}
import { step, getWorkflowMetadata, fetch } from 'workflow';

export async function notifyExternalSystem() {
  "use workflow";

  const { workflowRunId } = getWorkflowMetadata();

  await fetch('https://api.example.com/notify', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      runId: workflowRunId,
      message: 'Workflow started',
    }),
  });
}
```

### Create Webhook URLs

The `url` property is used internally by `createWebhook()`:

```typescript theme={null}
import { getWorkflowMetadata, createHook } from 'workflow';

export async function workflowWithCustomWebhook() {
  "use workflow";

  const { url } = getWorkflowMetadata();
  const hook = createHook();
  
  // Construct custom webhook URL
  const webhookUrl = `${url}/.well-known/workflow/v1/webhook/${hook.token}`;
  
  console.log('Send requests to:', webhookUrl);
  
  const request = await hook;
}
```

### Logging and Observability

Include workflow context in logs:

```typescript theme={null}
import { getWorkflowMetadata } from 'workflow';

export async function workflowWithLogging() {
  "use workflow";

  const { workflowRunId, workflowStartedAt } = getWorkflowMetadata();
  
  console.log({
    runId: workflowRunId,
    startedAt: workflowStartedAt.toISOString(),
    event: 'workflow_started',
  });
  
  await doWork();
  
  console.log({
    runId: workflowRunId,
    event: 'workflow_completed',
  });
}
```

### Correlation with External Systems

Use run ID for correlation:

```typescript theme={null}
import { step, getWorkflowMetadata } from 'workflow';

export async function workflowWithCorrelation() {
  "use workflow";

  const { workflowRunId } = getWorkflowMetadata();

  await step(async () => {
    "use step";
    
    // Use run ID as correlation ID in external systems
    await sendToMessageQueue({
      correlationId: workflowRunId,
      data: { /* ... */ },
    });
  });
}
```

### Unique Resource Names

Generate unique resource identifiers:

```typescript theme={null}
import { getWorkflowMetadata } from 'workflow';

export async function workflowWithUniqueResources() {
  "use workflow";

  const { workflowRunId } = getWorkflowMetadata();
  
  const bucketName = `workflow-${workflowRunId}`;
  const queueName = `queue-${workflowRunId}`;
  
  await createResources(bucketName, queueName);
}
```

### Scheduled Workflow Info

Combine with other metadata for scheduling:

```typescript theme={null}
import { getWorkflowMetadata, sleep } from 'workflow';

export async function scheduledWorkflow(scheduleTime: Date) {
  "use workflow";

  const { workflowStartedAt } = getWorkflowMetadata();
  
  // Calculate delay from when workflow started to scheduled time
  const delay = scheduleTime.getTime() - workflowStartedAt.getTime();
  
  if (delay > 0) {
    console.log(`Waiting ${delay}ms until scheduled time`);
    await sleep(delay);
  }
  
  await executeScheduledTask();
}
```

## Notes

* Can be called from both workflow functions and step functions
* Throws an error if called outside a workflow or step function
* The `workflowRunId` is guaranteed to be unique for each workflow run
* The `workflowStartedAt` timestamp represents when the workflow run was first started
* The `url` property contains the base URL for the workflow deployment
* Uses a symbol-based storage mechanism internally for context retrieval

## Related

* [getStepMetadata](/api-reference/workflow/get-step-metadata) - Get current step metadata
* [createWebhook](/api-reference/workflow/create-webhook) - Create a webhook (uses the `url` property)
* [getWritable](/api-reference/workflow/get-writable) - Get a writable stream for the workflow


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