# List runs

`GET` `/api/v1/crm-connections/{crm_connection_id}/distributions/runs`

Return distribution runs for the given Salesforce CRM connection.
Optionally filter by status. Supports sorting and cursor-based pagination.
Default page size is 50. Pass next_records_url from one response into
the next request to paginate through large result sets.

## Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| crm_connection_id | string | yes | UUID of the CRM connection |

## Query parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| query | string | no | Search by distribution definition name (min 2 characters) |
| status | string | no | Filter by run status: Pending, In Progress, Completed (default), or Failed |
| start_date | string | no | Include runs distributed on or after this date (YYYY-MM-DD) |
| end_date | string | no | Include runs distributed on or before this date (YYYY-MM-DD) |
| sort_by | string | no | Field to sort by: distributed_at (default), created_at, updated_at, or status |
| sort_direction | string | no | Sort direction: ASC or DESC (default: DESC) |
| limit | string | no | Maximum number of runs to return (default: 50). |
| next_records_url | string | no | Cursor returned by a previous response to fetch the next page. When provided, all other query params are ignored. |

## Response

`200 OK` — `application/json`

| Field | Type | Description |
|-------|------|-------------|
| runs | array[object] | List of distribution run records |
| runs.id | string | Run record ID |
| runs.definition | object | Distribution definition that produced this run |
| runs.definition.id | string | Salesforce ID of the definition |
| runs.definition.name | string | Definition name |
| runs.status | string | Run status: Pending, In Progress, Completed, or Failed |
| runs.status_message | string | Status message (typically set on failure) |
| runs.distributed_at | string | ISO-8601 timestamp when distribution ran |
| runs.created_at | string | ISO-8601 creation timestamp |
| runs.updated_at | string | ISO-8601 last-modified timestamp |
| runs.distributed_count | integer | Total accounts assigned in this run |
| next_records_url | string | Pass this value as next_records_url on the next request to fetch the following page. Null when all records have been returned. Only present when limit exceeds Salesforce's per-page maximum (2000 records). |

## Errors

| Status | Description |
|--------|-------------|
| 400 | Bad Request |
| 403 | Forbidden |
| 404 | Not Found |
| 422 | Unprocessable Entity |
| 502 | Bad Gateway |