> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dibby.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get run status

> Retrieve the status and results of a workflow run

## Overview

Use the `GET /runs/{runId}` endpoint to check the status of a workflow run and retrieve its results when complete.

## Path Parameters

<ParamField path="runId" type="string" required>
  The unique identifier of the workflow run (returned when you trigger a workflow)
</ParamField>

## Example Request

<CodeGroup>
  ```javascript JavaScript theme={null}
  const response = await fetch("https://dibby.ai/api/runs/run_abc123", {
    method: "GET",
    headers: {
      Authorization: "Bearer YOUR_TOKEN",
    },
  });

  const run = await response.json();
  console.log(run);
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://dibby.ai/api/runs/run_abc123",
      headers={
          "Authorization": "Bearer YOUR_TOKEN"
      }
  )

  run = response.json()
  print(run)
  ```

  ```bash cURL theme={null}
  curl -X GET https://dibby.ai/api/runs/run_abc123 \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```
</CodeGroup>

## Response

<ResponseField name="id" type="string">
  Unique identifier for this workflow run
</ResponseField>

<ResponseField name="versionName" type="string">
  Version of the workflow that was executed
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the run. Possible values:

  * `PENDING` - Workflow is queued
  * `RUNNING` - Workflow is currently executing
  * `FINISHED` - Workflow completed successfully
  * `FAILED` - Workflow encountered an error
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp when the run was created
</ResponseField>

<ResponseField name="steps" type="number">
  Total number of steps in the workflow
</ResponseField>

<ResponseField name="stepsCompleted" type="number">
  Number of steps completed so far
</ResponseField>

<ResponseField name="output" type="object">
  The workflow's output data. Only available when `status` is `FINISHED`.

  The structure matches your workflow's Result Node configuration.
</ResponseField>

## Response Examples

### Running workflow

<ResponseExample>
  ```json Running theme={null}
  {
    "id": "run_abc123",
    "versionName": "1.0",
    "status": "RUNNING",
    "createdAt": "2025-01-15T10:30:00Z",
    "steps": 5,
    "stepsCompleted": 3,
    "output": null
  }
  ```
</ResponseExample>

### Completed workflow

<ResponseExample>
  ```json Finished theme={null}
  {
    "id": "run_abc123",
    "versionName": "1.0",
    "status": "FINISHED",
    "createdAt": "2025-01-15T10:30:00Z",
    "steps": 5,
    "stepsCompleted": 5,
    "output": {
      "invoiceNumber": "INV-2025-001",
      "totalAmount": 1234.56,
      "vendor": "Acme Corp",
      "lineItems": [
        {
          "description": "Service Fee",
          "amount": 1000.00
        },
        {
          "description": "Tax",
          "amount": 234.56
        }
      ]
    }
  }
  ```
</ResponseExample>

### Failed workflow

<ResponseExample>
  ```json Failed theme={null}
  {
    "id": "run_abc123",
    "versionName": "1.0",
    "status": "FAILED",
    "createdAt": "2025-01-15T10:30:00Z",
    "steps": 5,
    "stepsCompleted": 2,
    "output": null,
    "error": {
      "message": "Failed to process document",
      "step": "Document Extractor"
    }
  }
  ```
</ResponseExample>

## Polling for results

Since workflows execute asynchronously, you'll typically need to poll this endpoint to wait for completion.

### Example polling implementation

```javascript theme={null}
async function waitForCompletion(runId, maxAttempts = 60, intervalMs = 2000) {
  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(`https://dibby.ai/api/runs/${runId}`, {
      headers: {
        Authorization: "Bearer YOUR_TOKEN",
      },
    });

    const run = await response.json();

    if (run.status === "FINISHED") {
      return run.output;
    }

    if (run.status === "FAILED") {
      throw new Error(`Workflow failed: ${run.error?.message}`);
    }

    // Wait before next poll
    await new Promise((resolve) => setTimeout(resolve, intervalMs));
  }

  throw new Error("Workflow timed out");
}

// Usage
try {
  const output = await waitForCompletion("run_abc123");
  console.log("Workflow completed:", output);
} catch (error) {
  console.error("Workflow error:", error);
}
```

## Best practices

### Polling intervals

* Start with 2-3 second intervals
* Consider exponential backoff for long-running workflows
* Set a reasonable timeout based on your workflow's expected duration

### Error handling

Always check the `status` field and handle all possible states:

```javascript theme={null}
const run = await fetch(`https://dibby.ai/api/runs/${runId}`, {
  headers: { Authorization: "Bearer YOUR_TOKEN" },
}).then((r) => r.json());

switch (run.status) {
  case "FINISHED":
    console.log("Success:", run.output);
    break;
  case "FAILED":
    console.error("Failed:", run.error);
    break;
  case "RUNNING":
  case "PENDING":
    console.log("Still processing...");
    break;
}
```

## Next steps

<Card title="Trigger a workflow" icon="play" href="/api-reference/endpoint/create">
  Learn how to trigger new workflow runs
</Card>