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

# List dispute service runs

`GET /dispute/disputes/runs`

## Request

- Base URL: `https://api.staging.payrails.io`
- URL: `https://api.staging.payrails.io/dispute/disputes/runs`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/payrails/apis/payrails-api-reference/docs/dispute/disputes/runs/get.ts> (a function with typed inputs; its response is checked against the schema)

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.dev/payrails/apis/payrails-api-reference.md) - [All operations](https://skmtc.dev/payrails/apis/payrails-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/payrails/apis/payrails-api-reference/revisions/9dd2f0158582?raw)