# List programs

`GET /programs`

- Base: `GET https://portal.watcheye.com.au/api/v1/programs`

Returns the programs belonging to the calling account.
[Soft-deleted](/docs/guides/watcheye_api/soft-deletion) programs are excluded.
Results are paginated.

## Filters

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

- `status` - one of `active`, `paused`

## Sorting

The `sort` query parameter accepts `created_at` (default: `-created_at`, newest first) or
`program_name`. Prefix with `-` for descending order.

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `page` | query | integer | The page number to return Example: `1` |
| `per_page` | query | integer | The number of programs 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` |
| `sort` | query | string | Field to sort by; prefix with `-` for descending order Enum: `created_at`, `-created_at`, `program_name`, `-program_name` Example: `-created_at` |

## Responses

### 200 Programs list response

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `data` | array of objects | An array of programs |
| `data[].uuid` | string (uuid) | The program's UUID Example: `9c3e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f` |
| `data[].program_number` | string | A short obfuscated public identifier for the program (e.g. "P-123-456-789") Example: `P-123-456-789` |
| `data[].program_name` | string | The display name of the program Example: `AML Onboarding Program` |
| `data[].status` | string | Lifecycle status of the program: * `active` - normal operation * `paused` - monitors do not run; entities and checks remain accessible * `archived` - read-only; the program is hidden from default lists but not deleted Enum: `active`, `paused`, `archived` Example: `active` |
| `data[].report_emails` | array of strings | Email addresses (max 5) that receive event report notifications for this program |
| `data[].data_retention_months` | integer | How long, in months, to keep entity data for. Permitted values: `0` (no retention), `1`, `3`, `6`, `12`, `24`, `36`, `48`, `60`, `72`, `84`. Example: `12` |
| `data[].event_grouping` | string | Whether events from the same entity should be grouped into one event: * `separate` - each event is created as a separate event (capped by `max_separate_events`) * `grouped` - events are merged into a single event per entity Enum: `separate`, `grouped` Example: `separate` |
| `data[].max_separate_events` | integer or null | When `event_grouping` is `separate`, the maximum number of separate events to create for a single entity (5-100). Null when `event_grouping` is `grouped`. Example: `10` |
| `data[].default_risk_level` | string or null | The risk level pre-filled when a new entity is added to this program: * `low` / `medium` / `high` - new entities pre-fill with this risk rating * `null` - new entities start with no risk assigned; the rating may be left unassigned and set later (bulk file uploads assign `low`) Enum: `low`, `medium`, `high` Example: `low` |
| `data[].created_at` | string (date-time) | ISO 8601 timestamp at which the program was created Example: `2025-01-01T00:00:00Z` |
| `data[].updated_at` | string (date-time) | ISO 8601 timestamp at which the program 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": "9c3e0a8e-2b9f-4f0e-8d1a-1e2b3c4d5e6f",
            "program_number": "P-123-456-789",
            "program_name": "AML Onboarding Program",
            "status": "active",
            "report_emails": [
                "compliance@example.com"
            ],
            "data_retention_months": 12,
            "event_grouping": "separate",
            "max_separate_events": 10,
            "default_risk_level": "low",
            "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, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))