---
title: "List workflow instances with current step info"
method: GET
path: "/v1/workflows/instances"
tags: ["Instances"]
---

# List workflow instances with current step info

`GET /v1/workflows/instances`

## Request

- Base URL: `https://api.paymongo.com`
- URL: `https://api.paymongo.com/v1/workflows/instances`
- Auth: none required

Returns paginated list of workflow execution instances with their current step status. Supports filtering by workflow_id, status, and current_step_status.

## Query parameters

- `workflow_id` string
- `status` 'running' | 'completed' | 'failed' | 'canceled' | 'terminated' | 'timed_out'
- `current_step_status` 'running' | 'completed' | 'failed' | 'canceled' | 'terminated' | 'timed_out'
- `source` string
- `external_id` string
- `external_id_prefix` string
- `limit` integer
- `after_id` string
- `before_id` string
- `sort_by` 'created_at' | 'updated_at'
- `sort_order` 'asc' | 'desc'

## Headers

- `Organization-Id` string, required

## Response `200`

List of instances

- ListInstancesResponse
  - `data` InstanceListItemDTO[]
    - `created_at` string
    - `current_step` CurrentStepDTO
      - `definition_path` string: Position of the step in the workflow definition, such as "2", "2.steps.0" or "0.then.1". A step recorded before positions were stored shows its step_index
      - `error` string: The failure reason. The stored chain for a superuser, the same text as error_detail for everyone else
      - `error_code` string: Why the step failed, from a closed set. internal_error when the step predates classification
      - `error_detail` string: What the caller is told about the failure
      - `input` object
      - `iteration` integer: 0-based loop iteration that ran the step; null when the step did not run inside a loop
      - `output` object
      - `started_at` string
      - `status` string
      - `step_index` integer
      - `step_name` string
      - `terminated_at` string
    - `idempotency_key` string
    - `instance_id` string
    - `internal` boolean
    - `livemode` boolean
    - `organization_id` string
    - `status` string
    - `terminated_at` string
    - `updated_at` string
    - `workflow_description` string
    - `workflow_id` string
    - `workflow_name` string
  - `has_more` boolean: HasMore is true when more results exist beyond this page: after the last row when paging forward, before the first row when paging backward with before_id.
  - `meta` MetaResponse
    - `limit` integer
  - `next_cursor` string: Opaque cursor for the last row on the page. Echo it as after_id to read the next page. It normally carries the sort it was issued under, so sort_by need not be repeated; for a very long text sort value the API falls back to a plain row id, which carries no sort, so a client pinning a non-default sort should keep sending sort_by. Omitted when the page has no rows.
  - `prev_cursor` string: Opaque cursor for the first row on the page. Echo it as before_id to read the previous page. It normally carries the sort it was issued under, so sort_by need not be repeated; for a very long text sort value the API falls back to a plain row id, which carries no sort, so a client pinning a non-default sort should keep sending sort_by. Omitted when the page has no rows.

## Other responses

- `400`: Invalid query parameters
- `401`: authentication_failed, missing_authorization_header, unsupported_auth_method or jwt_signature_invalid when the credential is missing, malformed or rejected; accountid_identity_required when a superuser or service-to-service caller sends the Account-ID header
- `500`: Internal server error
- `502`: accountid_relationship_lookup_failed or accountid_account_lookup_failed when an upstream service does not answer
- `503`: upstream_unavailable when an upstream service does not answer
- `504`: service_timeout when the request exceeds its deadline

---

[API](https://skmtc.dev/paymongo/apis/workflow.md) - [All operations](https://skmtc.dev/paymongo/apis/workflow/llms.txt) - [OpenAPI document](https://skmtc.dev/paymongo/apis/workflow/revisions/859719cfffa2?raw)