Run a monitor on demand

POST /api/v1/monitors/{monitor_uuid}/run operationId: monitor.run

Base: https://portal.watcheye.com.au/api/v1/monitors/{monitor_uuid}/run

Queues an immediate run of the monitor and returns 202 Accepted once the run has been scheduled. The actual screening happens in the background - poll GET /monitors/{monitor_uuid} and wait for process_status to transition out of pending / processing before reading the results.

Run types

The run_type field controls which entities the monitor processes:

new - process only entities created since the last run (the typical scheduled-run behaviour). On a never-run monitor this processes every active entity.
all - process every active entity in the program, regardless of when it was created or whether it has been processed before. Use this to re-screen everything from scratch (for example, after a config change).

Both modes only ever bill for entities that are eligible to be screened by the underlying operation (e.g. a UK ASIC check skips non-AU businesses).

Pre-flight checks

The endpoint runs several pre-flight checks before queueing the job. Each rejection is surfaced with a distinct status code so you can branch appropriately:

404 - the monitor was not found
409 Conflict - the monitor is not currently runnable. The most common cause is that the monitor is already mid-run (process_status of pending, processing or paused); other causes include the monitor being paused or the parent account being inactive. The body's message describes the reason.
402 Payment Required - the calling account has insufficient credit to cover the projected billable count. The response body includes a billing object with the cost breakdown so you can show the user exactly what would have been charged versus what they have available.

Idempotency

This endpoint accepts the Idempotency-Key header so that retries on network failure are safe. See the Idempotency section of the API guide for the full contract.

Path parameters

Field	Description
`monitor_uuid`required	string (uuid) The monitor UUID

Header parameters

Field Description

Field	Description
`Idempotency-Key`	string [max 255 characters] Optional client-generated key (typically a UUID) that lets you safely retry a write request without risk of duplicate work or duplicate billing. A retry with the same key and body returns the original response verbatim, with the `Idempotent-Replay: true` response header. Honoured on `POST` requests only. See the Idempotency section of the API guide for the full contract. Example: `8c4d3a18-2f63-4f9a-9f3a-9b1f5a7c2d4f`

Idempotency-Key

string [max 255 characters]

Optional client-generated key (typically a UUID) that lets you safely retry a write request without risk of duplicate work or duplicate billing. A retry with the same key and body returns the original response verbatim, with the Idempotent-Replay: true response header.

Honoured on POST requests only. See the Idempotency section of the API guide for the full contract.

Example: 8c4d3a18-2f63-4f9a-9f3a-9b1f5a7c2d4f

Request body

Content type application/json. The run parameters

Field Description

Field	Description
`run_type`required	string Which entities to process. See the description above for the difference between `new` and `all`. Enum: `new`, `all` Example: `new`

run_typerequired

string

Which entities to process. See the description above for the difference between new and all.

Enum: new, all

Example: new

Responses

202

Run accepted - the monitor has been queued for processing. The response body shows the monitor with `process_status: pending`. Poll the show endpoint to observe the status transition out of `pending`/`processing`.

application/json

Field	Description
`data`	object A monitor is a scheduled (or manual) screening job that runs a single screening operation (PEP/sanction, ASIC, address verification, etc.) against the entities in its parent program. The operation type is fixed at creation; only configuration, name, status and schedule can be changed after that.
`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 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`
`api_reference`	string (uuid)

409

Conflict - the monitor cannot be run in its current state. The most common cause is that the monitor is already mid-run; other causes include the monitor being paused or the parent account being inactive.

application/json

Field	Description
`message`	string Example: `Monitor cannot be run while it is already pending`

422

Idempotency-Key was reused with a different request body

application/json

Field	Description
`message`	string Example: `Idempotency-Key was reused with a different request body.`

Standard error responses: 400 401 402 403 404 429 5XX See common error responses

Previous Delete a monitor Next List notes

Request body application/json

{
    "run_type": "new"
}

Response

202 Run accepted - the monitor has been queued for processing. The response body shows the monitor with process_status: pending. Poll the show endpoint to observe the status transition out of pending/processing.

{
    "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"
    },
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

400 Bad Request - The request is invalid shared error response

{
    "message": "Bad Request",
    "api_reference": "00000000-0000-0000-0000-000000000000",
    "errors": {
        "data.passport_number": [
            "The passport number format is invalid."
        ]
    }
}

401 Unauthorized - the API key or account is inactive, expired, or not permitted from this IP address shared error response

{
    "message": "API Key Inactive",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

402 Insufficient Credit - Insufficient credit to process this request shared error response

{
    "message": "Insufficient Credit",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

403 No access - No permission to process this request shared error response

{
    "message": "No access",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

404 Not Found - The requested resource does not exist or is not accessible by this account shared error response

{
    "message": "Entity not found",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

409 Conflict - the monitor cannot be run in its current state. The most common cause is that the monitor is already mid-run; other causes include the monitor being paused or the parent account being inactive.

{
    "message": "Monitor cannot be run while it is already pending"
}

422 Idempotency-Key was reused with a different request body

{
    "message": "Idempotency-Key was reused with a different request body."
}

429 Rate limited - The request rate limit has been reached shared error response

{
    "message": "Rate limited",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

5XX Internal error - Internal system error shared error response

{
    "message": "Internal error",
    "api_reference": "00000000-0000-0000-0000-000000000000"
}

Run a monitor on demand

Run types

Pre-flight checks

Idempotency

Path parameters

Header parameters

Request body

Responses

Run accepted - the monitor has been queued for processing. The response body shows the monitor with process_status: pending. Poll the show endpoint to observe the status transition out of pending/processing.

Conflict - the monitor cannot be run in its current state. The most common cause is that the monitor is already mid-run; other causes include the monitor being paused or the parent account being inactive.

Idempotency-Key was reused with a different request body

Run accepted - the monitor has been queued for processing. The response body shows the monitor with `process_status: pending`. Poll the show endpoint to observe the status transition out of `pending`/`processing`.