# List monitors in a program

`GET /programs/{program_uuid}/monitors`

- Base: `GET https://portal.watcheye.com.au/api/v1/programs/{program_uuid}/monitors`

Returns the monitors that belong to the given program.
[Soft-deleted](/docs/guides/watcheye_api/soft-deletion) monitors are excluded.
Results are paginated.

## Filters

The following filters can be applied via the `filter[...]` query parameters:

- `status` - one of `active`, `paused`
- `process_status` - one of `pending`, `processing`, `failed`, `paused`
- `monitor_check_type` - one of the operation types enabled on the account
- `schedule` - one of the schedule values listed on the Monitor schema

## Sorting

The `sort` query parameter accepts `created_at`, `last_run_at` (default: `-last_run_at`,
most recently run first - monitors that have never run sort last) or `monitor_name`.
Prefix with `-` for descending order.

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `program_uuid` | path | string (uuid) | **Required.** The program UUID |
| `page` | query | integer | The page number to return Example: `1` |
| `per_page` | query | integer | The number of monitors per page (defaults to 30, max 500) Example: `30` |
| `filter[status]` | query | string | Only records with the given status. The endpoint description lists the values. Enum: `active`, `paused` |
| `filter[process_status]` | query | string | Only monitors with the given process status. Enum: `pending`, `processing`, `failed`, `paused` |
| `filter[monitor_check_type]` | query | string | Only monitors of the given operation type. |
| `filter[schedule]` | query | string | Only monitors on the given schedule. |
| `sort` | query | string | Field to sort by; prefix with `-` for descending order Enum: `created_at`, `-created_at`, `last_run_at`, `-last_run_at`, `monitor_name`, `-monitor_name` Example: `-last_run_at` |

## Responses

### 200 Monitors list response

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `data` | array of objects | An array of monitors |
| `data[].uuid` | string (uuid) | The monitor's UUID Example: `5d6c8f93-91d4-4d6a-bb5e-2c64e9a3b1f0` |
| `data[].monitor_number` | string | A short obfuscated public identifier for the monitor (e.g. "M-12-34-56") Example: `M-12-34-56` |
| `data[].monitor_name` | string | The display name of the monitor Example: `Weekly PEP Sweep` |
| `data[].monitor_check_type` | string | The screening operation this monitor runs. Cannot be changed after creation - create a new monitor instead. The list of allowed values depends on the products enabled on the calling account. Example: `pep_sanction_check` |
| `data[].monitor_check_type_name` | string | Human-readable name for `monitor_check_type` (e.g. "PEP & Sanction Check") Example: `PEP & Sanction Check` |
| `data[].status` | string | Lifecycle status: * `active` - the monitor runs on its schedule and can be triggered manually * `paused` - the monitor does not run on its schedule and cannot be triggered manually Enum: `active`, `paused` Example: `active` |
| `data[].process_status` | string or null | In-flight run state, or `null` when the monitor is idle: * `pending` - queued * `processing` - currently running * `failed` - the most recent run failed (cleared on next successful run) * `paused` - the run was paused mid-flight (e.g. due to insufficient credit) Callers polling after `POST /monitors/{uuid}/run` should wait for this field to transition out of `pending`/`processing` before reading results. Enum: `pending`, `processing`, `failed`, `paused` |
| `data[].process_status_comment` | string or null | Optional human-readable detail accompanying `process_status` (e.g. failure message) |
| `data[].schedule` | string | How often the monitor runs unattended. `manual` means it never runs on its own and must be triggered via the run endpoint. Enum: `manual`, `every_day`, `weekdays`, `weekends`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`, `sunday`, `monthly_1`, `monthly_15`, `monthly_1_15`, `quarterly` Example: `weekdays` |
| `data[].schedule_name` | string or null | Human-readable description of the schedule (e.g. "Every Day (Mon-Sun)") Example: `Weekdays (Mon-Fri)` |
| `data[].config` | object (dynamic) | Per-operation configuration. The shape depends on `monitor_check_type`; see the [Monitor Configuration](/docs/guides/watcheye_api/monitor-configuration) section of the API guide for the schema of each operation. The portal's monitor create/edit screens render the same fields you'd send here. |
| `data[].last_run_at` | string (date-time) or null | ISO 8601 timestamp of the most recent run, or `null` if the monitor has never run Example: `2025-01-15T03:00:00Z` |
| `data[].has_run_before` | boolean | `true` if the monitor has processed at least one entity. Used by the "new" run mode to know whether there is a cursor to resume from. Example: `true` |
| `data[].program_uuid` | string (uuid) | UUID of the program this monitor belongs to Example: `9c3e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f` |
| `data[].created_at` | string (date-time) | ISO 8601 timestamp at which the monitor was created Example: `2025-01-01T00:00:00Z` |
| `data[].updated_at` | string (date-time) | ISO 8601 timestamp at which the monitor was last updated Example: `2025-01-01T00:00:00Z` |
| `meta` | object |  |
| `meta.current_page` | integer | Example: `1` |
| `meta.per_page` | integer | Example: `30` |
| `meta.total` | integer | Example: `1` |
| `meta.last_page` | integer | Example: `1` |
| `api_reference` | string (uuid) | A unique identifier for this request. This can be used to track the request in the logs and audit trail. |

**Sample response**

```json
{
    "data": [
        {
            "uuid": "5d6c8f93-91d4-4d6a-bb5e-2c64e9a3b1f0",
            "monitor_number": "M-12-34-56",
            "monitor_name": "Weekly PEP Sweep",
            "monitor_check_type": "pep_sanction_check",
            "monitor_check_type_name": "PEP & Sanction Check",
            "status": "active",
            "process_status": null,
            "process_status_comment": null,
            "schedule": "weekdays",
            "schedule_name": "Weekdays (Mon-Fri)",
            "config": {
                "search_type": "pep_and_sanction",
                "similarity_threshold": 90
            },
            "last_run_at": "2025-01-15T03:00:00Z",
            "has_run_before": true,
            "program_uuid": "9c3e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f",
            "created_at": "2025-01-01T00:00:00Z",
            "updated_at": "2025-01-01T00:00:00Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 30,
        "total": 1,
        "last_page": 1
    },
    "api_reference": "00000000-0000-0000-0000-000000000000"
}
```

Standard error responses: 400, 401, 402, 403, 404, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))