Get run status

Get run status

curl --request GET \
  --url https://dibby.ai/api/runs/{runId}

import requests

url = "https://dibby.ai/api/runs/{runId}"

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://dibby.ai/api/runs/{runId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://dibby.ai/api/runs/{runId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://dibby.ai/api/runs/{runId}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://dibby.ai/api/runs/{runId}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://dibby.ai/api/runs/{runId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

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

GET

runs

{runId}

Get run status

curl --request GET \
  --url https://dibby.ai/api/runs/{runId}

import requests

url = "https://dibby.ai/api/runs/{runId}"

response = requests.get(url)

print(response.text)

const options = {method: 'GET'};

fetch('https://dibby.ai/api/runs/{runId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://dibby.ai/api/runs/{runId}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://dibby.ai/api/runs/{runId}"

	req, _ := http.NewRequest("GET", url, nil)

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://dibby.ai/api/runs/{runId}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://dibby.ai/api/runs/{runId}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

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

import requests

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

run = response.json()
print(run)

curl -X GET https://dibby.ai/api/runs/run_abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

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

Introduction Trigger a workflow

API Documentation

Endpoints

Overview

Path Parameters

Example Request

Response

Response Examples

Running workflow

Completed workflow

Failed workflow

Polling for results

Example polling implementation

Best practices

Polling intervals

Error handling

Next steps

Trigger a workflow

​Overview

​Path Parameters

​Example Request

​Response

​Response Examples

​Running workflow

​Completed workflow

​Failed workflow

​Polling for results

​Example polling implementation

​Best practices

​Polling intervals

​Error handling

​Next steps

Trigger a workflow

Overview

Path Parameters

Example Request

Response

Response Examples

Running workflow

Completed workflow

Failed workflow

Polling for results

Example polling implementation

Best practices

Polling intervals

Error handling

Next steps