Skip to main content
GET
/
runs
/
{runId}
Get run status
curl --request GET \
  --url https://api.example.com/runs/{runId}
{
  "id": "run_abc123",
  "versionName": "1.0",
  "status": "RUNNING",
  "createdAt": "2025-01-15T10:30:00Z",
  "steps": 5,
  "stepsCompleted": 3,
  "output": null
}

​
Overview

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

​
Path Parameters

​
runId
string
required
The unique identifier of the workflow run (returned when you trigger a workflow)

​
Example Request

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

​
Response

​
id
string
Unique identifier for this workflow run
​
versionName
string
Version of the workflow that was executed
​
status
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
​
createdAt
string
ISO 8601 timestamp when the run was created
​
steps
number
Total number of steps in the workflow
​
stepsCompleted
number
Number of steps completed so far
​
output
object
The workflow’s output data. Only available when status is FINISHED.The structure matches your workflow’s Result Node configuration.

​
Response Examples

​
Running workflow

{
  "id": "run_abc123",
  "versionName": "1.0",
  "status": "RUNNING",
  "createdAt": "2025-01-15T10:30:00Z",
  "steps": 5,
  "stepsCompleted": 3,
  "output": null
}

​
Completed workflow

{
  "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
      }
    ]
  }
}

​
Failed workflow

{
  "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"
  }
}

​
Polling for results

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

​
Example polling implementation

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

Trigger a workflow

Learn how to trigger new workflow runs