The Workflow API exposes five read endpoints for inspecting what your workflows are doing. Pair them with the wait-state endpoints (Beta) to track workflows paused on wait_event steps.

Listing instances

GET /v1/instances returns the most recent instances for your organization, with filters for the most common queries.

curl --request GET 'https://workflow-api.paymongo.com/v1/instances?workflow_id=wf_abc123&status=running&limit=20' \
  --header 'Authorization: Basic ${YOUR_BASIC_TOKEN}' \
  --header 'Organization-Id: ${YOUR_ORG_ID}'

Useful filters:

Query parameter	Description
`workflow_id`	Limit to instances of one workflow.
`status`	One of `running`, `completed`, `failed`, `canceled`, `terminated`, `timed_out`.
`limit`	Page size (default 10, max 100).
`offset`	Pagination offset.
`sort_by`	`created_at` or `updated_at`.
`sort_order`	`asc` or `desc` (default `desc`).

The response is paginated and includes a summary current_step per instance: the step that is currently running, or the latest step if the instance has finished.

Reading one instance

GET /v1/instances/:id returns the full instance state including every step's current status.

curl --request GET 'https://workflow-api.paymongo.com/v1/instances/inst_xyz' \
  --header 'Authorization: Basic ${YOUR_BASIC_TOKEN}' \
  --header 'Organization-Id: ${YOUR_ORG_ID}'

The response shape:

{
  "data": {
    "instance_id": "inst_xyz",
    "workflow_id": "wf_abc123",
    "status": "completed",
    "input": { "...": "..." },
    "output": {
      "steps_executed": 2,
      "step_outputs": [
        {"status": "completed", "transfer_id": "tr_..."},
        {"status": "completed"}
      ]
    },
    "steps": [
      {"step_index": 0, "status": "completed", "started_at": "...", "terminated_at": "..."},
      {"step_index": 1, "status": "completed", "started_at": "...", "terminated_at": "..."}
    ],
    "created_at": "...",
    "updated_at": "...",
    "terminated_at": "..."
  }
}

Step history

The Workflow API exposes three different views of step state. Choose the one that matches your question.

Endpoint	Returns	When to use
`GET /v1/instances/:id/steps/current`	Latest state of every step in the instance.	Quick "where is this workflow now" view.
`GET /v1/instances/:id/history`	Every retry attempt for every step in the instance.	Auditing a finished or failed instance.
`GET /v1/instances/:id/steps/:index/history`	Every retry attempt for one specific step (database-backed, fast).	Investigating a specific step's failure history.

Each step history record carries:

Field	Description
`step_index`	Zero-based position of the step in the workflow.
`step_name`	The user-supplied step `name`, when present.
`attempt`	Which retry attempt this record is for (1-indexed).
`status`	Final status for this attempt (`completed`, `failed`, `running`, `pending`, `timed_out`, `canceled`, `terminated`).
`input`	The resolved step input for this attempt.
`output`	The step's output, if it completed.
`error`	The error message, if the attempt failed.
`started_at`	When this attempt started.
`terminated_at`	When this attempt ended. Empty if still running.
`duration_ms`	Computed duration in milliseconds. Empty if still running.

Wait states (Beta)

Workflows paused on a wait_event step do not change their instance status to "waiting"; there is no such status. Instead, a separate wait_state row is created. Use the wait-state endpoints to find paused work.

Endpoint	Returns
`GET /v1/instances/waiting`	All currently-waiting instances for your organization, with filters by `workflow_id` and `event_name`.
`GET /v1/instances/:id/wait-states`	The wait-state row(s) for a specific instance.

A wait-state row carries the configured event_name, the timeout_at deadline, the current attempt and max attempts, and the status (waiting, completed, timed_out, cancelled).

To submit an event that satisfies a wait, see Submit an Event and the Wait Event Step guide.

Common patterns

Is my workflow stuck?

Use GET /v1/instances/:id/steps/current. If a step shows status: running for longer than expected, fetch its history with GET /v1/instances/:id/steps/:index/history to see retry attempts.

Did the second step fail?

Use GET /v1/instances/:id/steps/1/history. Step indexes are zero-based, so the second step is index 1. Look at the most recent attempt's error.

Find every instance waiting on a specific event

Use GET /v1/instances/waiting?event_name=delivery.confirmed. The endpoint returns all currently-waiting instances regardless of which workflow they belong to.

Observing Workflow Runs

Listing instances

Reading one instance

Step history

Wait states (Beta)

Common patterns

See also