# Follow a workflow run

> Find a recent workflow run, retrieve its current state, and inspect safe per-step outcomes without exposing payloads.

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:

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

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

```bash
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](/reference/json-api/runs-monitoring):

```json
{
  "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](/webhook-ingestion/first-delivery) and follow its returned run ID.
- [Read errors and request IDs](/platform/errors-request-ids).
- Browse [Runs and monitoring operations](/reference/json-api/runs-monitoring).