Follow a workflow run

Observe a workflow run through JSON:API. The API exposes state, timing, and safe error metadata; it does not serialize step payloads or internal execution data.

What you will do

1. List at most ten recent visible runs.
2. Choose one run ID.
3. Retrieve the run until it reaches a terminal or waiting state.
4. Inspect its per-step outcomes through the dedicated steps operation.

Prerequisites

• A saved workflow has executed at least once. Trigger it through its normal product path; this guide does not create a run.
• A service account in the same workspace with api_read.
• An active run-as member allowed to see the workflow.
• HODOFLOW_BASE_URL, TOKEN, cURL, and jq.

If you just sent a webhook delivery, use the returned workflow_run_id and skip the list step.

Request

List a small page of runs:

RUNS_RESPONSE="$(
  curl --silent --show-error --globoff \
    --header "Accept: application/vnd.api+json" \
    --header "Authorization: Bearer $TOKEN" \
    "$HODOFLOW_BASE_URL/api/json/v1/workflow_runs?page[limit]=10&sort=-inserted_at"
)"

printf '%s\n' "$RUNS_RESPONSE" | jq .
RUN_ID="$(printf '%s\n' "$RUNS_RESPONSE" | jq -er '.data[0].id')"

Retrieve the chosen run:

curl --silent --show-error \
  --header "Accept: application/vnd.api+json" \
  --header "Authorization: Bearer $TOKEN" \
  "$HODOFLOW_BASE_URL/api/json/v1/workflow_runs/$RUN_ID" |
  jq .

The run-steps projection does not expose a page parameter, so it is the documented no-pagination exception. It returns the bounded set of steps from that one workflow run.

Poll only when your integration truly needs completion. Use increasing delays, stay within the rate budget, and stop on a terminal state. Keep the x-request-id from any failure.

Then inspect safe step outcomes:

curl --silent --show-error \
  --header "Accept: application/vnd.api+json" \
  --header "Authorization: Bearer $TOKEN" \
  "$HODOFLOW_BASE_URL/api/json/v1/workflow_runs/$RUN_ID/steps" |
  jq .

Expected response

The run detail returns 200 OK and one workflow_run resource. Exact public attributes are listed in the Runs reference:

{
  "data": {
    "type": "workflow_run",
    "id": "00000000-0000-4000-8000-000000000001",
    "attributes": {
      "state": "completed",
      "started_at": "2026-07-31T18:30:00Z",
      "completed_at": "2026-07-31T18:30:02Z",
      "error_message": null
    }
  }
}

The steps operation returns an array of projected step outcomes with identifier, status, timing, and safe error information. It intentionally omits step input and output payloads.

Troubleshooting

• Empty run list: the workspace has no visible runs. Execute a workflow or use Monitor to confirm the intended workspace.
• 401: exchange once and retry once.
• 403: correct api_read or run-as access.
• 404: the run may belong to another workspace or be hidden from the run-as member; do not scan IDs.
• 429: stop polling for Retry-After seconds and increase the interval.
• A waiting or suspended state is not automatically a failure; inspect its public reason and the workflow's product configuration.

Unset RUNS_RESPONSE and RUN_ID when finished.

Next steps

• Send a webhook delivery and follow its returned run ID.
• Read errors and request IDs.
• Browse Runs and monitoring operations.