PApaymongo
Instances

List workflow instances with current step info

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

get/v1/workflows/instances

Request

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

Query parameters

workflow_idstring

Filter by workflow ID

status'running' | 'completed' | 'failed' | 'canceled' | 'terminated' | 'timed_out'

Filter by instance status

current_step_status'running' | 'completed' | 'failed' | 'canceled' | 'terminated' | 'timed_out'

Filter by current step status

sourcestring

Filter by external reference source

external_idstring

Filter by external reference external ID

external_id_prefixstring

Filter by external reference ID prefix; returns all matching instances (mutually exclusive with external_id)

limitinteger

Page size (default: 10, max: 100)

after_idstring

Return the page after this position: either the opaque next_cursor from a previous response, or a bare instance ID; excludes before_id

before_idstring

Return the page before this position: either the opaque prev_cursor from a previous response, or a bare instance ID; excludes after_id

sort_by'created_at' | 'updated_at'

Sort column (default: created_at descending)

sort_order'asc' | 'desc'

Sort direction; requires sort_by

Headers

Organization-Idstring required

Organization ID

Response

List of instances

has_moreboolean

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.

next_cursorstring

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_cursorstring

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.

Example response

{
  "data": [
    {
      "created_at": "2026-01-15 10:30:00+00:00",
      "current_step": {
        "definition_path": "2.steps.0",
        "error": "a workflow step failed",
        "error_code": "step_execution_failed",
        "error_detail": "a workflow step failed",
        "started_at": "2026-01-15 10:30:00+00:00",
        "status": "completed",
        "step_name": "validate_amount",
        "terminated_at": "2026-01-15 10:31:00+00:00"
      },
      "idempotency_key": "idem_abc123",
      "instance_id": "inst_abc123",
      "livemode": true,
      "organization_id": "org_abc123",
      "status": "running",
      "terminated_at": "2026-01-15 10:31:00+00:00",
      "updated_at": "2026-01-15 10:30:00+00:00",
      "workflow_description": "Handles merchant payout disbursement",
      "workflow_id": "flow_abc123",
      "workflow_name": "Payout Workflow"
    }
  ],
  "meta": {
    "limit": 10
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.