---
title: "List dispute service runs"
method: GET
path: "/dispute/disputes/runs"
tags: ["Disputes"]
---

# List dispute service runs

`GET /dispute/disputes/runs`

List asynchronous runs in the dispute service, scoped to the workspaces you can access. Runs back operations such as a backfill, which pulls disputes and their related payments from the provider into your dispute and payment records. Use the filters to narrow by run type, status, or resolution; results are ordered most-recent first.

## Query parameters

- `filter[runType]` string
- `filter[status]` 'queued' | 'dispatched' | 'done'
- `filter[resolution]` 'success' | 'failed' | 'cancelled'

## Response `200`

Success.

- object — A paginated list of dispute service runs.
  - `links` object
    - `self` string, required
    - `prev` string
    - `next` string
    - `first` string
    - `last` string
  - `results` object[], required
    - `id` string, uuid, required — Unique identifier of the run.
    - `workspaceId` string, uuid — Workspace the run belongs to. Omitted for runs that are not scoped to a single workspace.
    - `runType` string, required — The kind of work the run performs, for example `dispute-pull-controller` (owns the cursor for one provider configuration) or `dispute-pull-window` (pulls disputes and their related payments for one time window).
    - `status` 'queued' | 'dispatched' | 'done', required — Lifecycle state of the run.
    - `resolution` 'success' | 'failed' | 'cancelled' — Outcome of a completed run. Absent until the run reaches `done`.
    - `errors` string[] — Error messages collected during execution, when the run did not fully succeed.
    - `params` object — The arguments the run was started with. The shape depends on `runType`; a dispute-pull run carries `providerConfigId`, optional `paymentProviderConfigId`, and the `dateFrom` / `dateTo` window.
    - `summary` object — Aggregate result of the run. The shape depends on `runType`; a dispute-pull window reports `disputesPulled`, `disputesUpserted`, `paymentsPulled`, `paymentsUpserted` and any `unsupportedOps`.
    - `input` object — Trigger metadata for the run, such as the resolved window or cursor.
    - `parentRunId` string, uuid — For a child run, the identifier of the run that spawned it (for example a dispute-pull window's controller). Absent for top-level runs.
    - `startedAt` string, date-time — Date and time when the run started executing.
    - `completedAt` string, date-time — Date and time when the run finished. Absent until the run reaches `done`.
    - `createdAt` string, date-time, required — Date and time when the run was created.
    - `updatedAt` string, date-time, required — Date and time when the run was last updated.
    - `jobs` object[] — The run's execution attempts, most recent first. Included only when a single run is retrieved by id.
      - `id` string, uuid, required — Unique identifier of the run job.
      - `runId` string, uuid, required — Identifier of the run this attempt belongs to.
      - `eventId` string — Idempotency reference for the attempt.
      - `externalReference` string — Reference to the external execution backing this attempt, when applicable.
      - `status` 'queued' | 'dispatched' | 'done', required — Lifecycle state of the attempt.
      - `resolution` 'success' | 'failed' | 'cancelled' — Outcome of the attempt. Absent until the attempt reaches `done`.
      - `errors` string[] — Error messages collected during the attempt.
      - `summary` object — Aggregate result of the attempt; shape depends on the run type.
      - `input` object — Trigger metadata for the attempt, such as the resolved window or cursor.
      - `startedAt` string, date-time — Date and time when the attempt started executing.
      - `completedAt` string, date-time — Date and time when the attempt finished.
      - `createdAt` string, date-time, required — Date and time when the attempt was created.

## Other responses

- `400` — Bad Request.
- `401` — Unauthorized.
- `403` — Insufficient Scope.
- `429` — Too Many Requests.

---

[API](https://skmtc.net/payrails/apis/payrails-api-reference.md) · [All operations](https://skmtc.net/payrails/apis/payrails-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/payrails/payrails-api-reference/versions/9dd2f0158582/schema)