# Monitors

Run an API on a schedule with saved input and get the result at your webhook, when it changes or after every run. Credits, schedules, failures, your own ids, keys, run now, and the endpoints.

A monitor runs one API on a schedule, with input you save once, and sends the result to your webhook URL. Watch a profile, a search or a listing, and hear about it when the answer changes, without running a scheduler yourself.

```bash
curl -sS -X POST "https://api.primaryapi.com/v1/monitors" \
  -H "Authorization: Bearer $PRIMARYAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sku": "instagram.profile",
    "input": { "username": "natgeo" },
    "intervalSeconds": 3600,
    "webhookUrl": "https://example.com/hooks/primaryapi",
    "customId": "crm-account-1042"
  }'
```

The first run happens within a minute. After that it runs every hour, and your webhook receives a signed `monitor.run.succeeded` event the first time and whenever the profile changes. [Webhooks](/docs/webhooks) shows what arrives and how to verify it.

## How a monitor works

- **A run is an ordinary call.** It runs the API with the saved input exactly as `POST /v1/run/{sku}` would: the same credits, held and settled the same way, nothing when the call fails. Every run appears in your request history (`GET /v1/requests`) and in Usage.
- **You choose when to hear about it.** `notify: "change"` (the default) sends the first result and then only results that differ from the last successful run. `notify: "always"` sends every successful run. Failed runs send `monitor.run.failed` while `notifyFailures` is on (the default).
- **A few failures don't stop it.** A failed run doesn't pause the monitor. Only when 10 runs in a row have failed do we pause it ([below](#when-runs-keep-failing)).
- **Any interval** from 1 minute to 30 days, in seconds. The dashboard offers presets (every minute, 5, 15 or 30 minutes, every hour, 6 or 12 hours, every day, every week) and a custom value.
- **No backlog.** A monitor never runs twice at the same time. If a run takes longer than the interval, or our service was briefly unavailable, the runs it missed become one run, and the schedule keeps its rhythm.
- **Signed webhooks with retries.** Every event is signed with your workspace's secret and retried after a failed delivery: 5 seconds, 30 seconds, 2, 5 and 15 minutes, then 1, 4, 12, 24 and 48 hours.

## Credits

A run costs what the API costs for the saved input, the same as calling it yourself ([Pricing and billing](/docs/pricing-and-billing)). Like any call, the most it can cost is held when the run starts and the rest comes back the moment it ends.

- A run is charged whether or not it sends a webhook: with `notify: "change"`, an unchanged answer still cost the call. The notify mode decides what you hear about, not what you pay.
- Failed runs cost nothing. Skipped runs (below) cost nothing.
- Runs a month is about `2,592,000 ÷ intervalSeconds` (30 days). Every 15 minutes is 2,880 runs; every hour 720; every day 30. Multiplied by the API's price that is the most a monitor can spend in a month.
- To cap what a monitor can spend, run it with an API key that has a spend limit (`keyId`, below). The key's limit applies to every run, exactly as to its own calls.

## Skipped runs

A run that cannot start is **skipped**: it is free, it is recorded with its reason, it sends no webhook, and the monitor keeps its schedule.

| `reason` | What happened |
| --- | --- |
| `insufficient_credits` | The workspace's credits cannot cover the most the call could cost. Buy credits, or turn on auto top-up. |
| `key_limit` | The monitor's key reached its spend limit for the current window. |
| `trial_cap` | The monitor's key is an agent trial key that has spent its trial credits. |
| `key_disabled`, `key_expired`, `key_revoked` | The monitor's key can no longer be used. Pick another key, or none, with `PATCH /v1/monitors/{id}`. |
| `key_access` | The monitor's key has `view` access, which cannot run APIs. |
| `restricted_api` | The API returns sensitive personal data and this workspace is not approved for it. See [Restricted APIs](/docs/restricted-apis). |
| `api_unavailable` | The API cannot be served right now. |
| `api_removed` | The API is no longer in the catalog. |

A **failed** run started a call that did not succeed. Its `reason` is the call's error code (`all_sources_failed`, `timeout`, `invalid_input` …, see [Errors](/docs/errors)), or `interrupted` when our service stopped in the middle of a run. Failed runs are free.

## When runs keep failing

A failed run doesn't pause a monitor: it keeps its schedule, and every failure sends `monitor.run.failed` while `notifyFailures` is on. We count failed runs in a row, and the **10th** one pauses the monitor.

- **A run fails** when its call failed, or when its call succeeded but its webhook was still undelivered after every retry (your endpoint didn't answer with a `2xx` for 11 attempts).
- **A run succeeds** when its call succeeded and its webhook was delivered, or no webhook was due (`notify: "change"` and nothing changed).
- **Skipped runs** count as neither: they neither end the failures nor add to them.
- **Each run counts once.** A failed run whose failure event can't be delivered is one failure, not two. Test events and redeliveries never count.
- A run whose webhook is still being retried counts when that delivery is done, which can be hours or days later. Counts follow the order outcomes arrive in.
- The monitor shows `consecutiveFailures` (failed runs in a row) and `failingSince` (when the first of them started). A success sets them back to `0` and `null`.
- When the 10th failure in a row lands, we pause the monitor: `status: "paused"`, `pausedReason: "failing"`, `nextRunAt: null`. When that failure is a failed call, its `monitor.run.failed` event carries `monitorPaused: { "reason": "failing", "failingSince": "…", "consecutiveFailures": 10 }` ([Webhooks](/docs/webhooks#monitor-events)). With `notifyFailures` off, or when the 10th failure is an undelivered webhook, the pause happens without an event and shows on the monitor in the dashboard and the API.
- Fix the cause (fix your webhook receiver, change the input, pick another key), then resume it with `{"status": "active"}`. Resuming clears `pausedReason`, `failingSince` and `consecutiveFailures`, so the count starts again.
- A monitor you paused yourself is never given a reason, even if Run now keeps failing on it (those runs still count).

## Change detection

`notify: "change"` compares each successful run's `output` (`found`, `data` and `reason`, as in the [run envelope](/docs/making-requests)) with the output of the last successful run. The comparison ignores the order of object keys and keeps the order of lists, so the same answer is never reported as a change.

- The first successful run always counts as a change, so you receive the starting point.
- Changing a monitor's `input` starts over: the next successful run counts as a first run.
- Every run reports `changed` either way, also with `notify: "always"`.

Some APIs return values that differ on every call, such as a timestamp of when the data was read. With those, every run is a change.

## Your own ids

`customId` is your reference for the monitor, typically the id of the record it watches in your own system: letters, digits and `. _ - : / @`, up to 128 characters. It is optional and comes back in every event.

- It is unique among the workspace's monitors that are not deleted. Reusing one answers `409 custom_id_taken`, with the existing monitor's id in `details.monitorId`. Deleting a monitor frees its `customId`.
- Find a monitor by it with `GET /v1/monitors/by-custom-id/{customId}` (URL-encode it: `crm/42` becomes `crm%2F42`) or filter a list with `GET /v1/monitors?customId=…`.

## Keys and who can do what

- **Created with an API key**, a monitor runs as that key: with its access, and within its spend limit. A `run` key can change, run and delete only the monitors that run with it; a `full` key can change any monitor of the workspace; a `view` key can only read them.
- **Created in the dashboard**, the key is optional. With a key, runs use it as above. Without one, runs are charged to the workspace with no key limit, and count toward the member who set the monitor up in Usage.
- In the dashboard, owners, admins and developers create and change monitors; every member can read them.
- Monitors belong to the workspace: they keep running when the person who made them leaves the workspace, and they are deleted with the workspace.

## Pause, run now and test

- `PATCH /v1/monitors/{id}` with `{"status": "paused"}` stops the schedule; `{"status": "active"}` resumes it, and the monitor runs within a minute. Resuming also clears `pausedReason`, `failingSince` and `consecutiveFailures`.
- `POST /v1/monitors/{id}/run` runs it now, also while it is paused, charged like any call. The schedule stays as it was. While a run is in progress the answer is `422 unprocessable`: try again when it has finished.
- `POST /v1/monitors/{id}/test` sends a `monitor.test` event to the webhook URL. It is free and runs nothing.

## Limits

- A workspace keeps at most 1,000 monitors that are not deleted (`422 unprocessable` beyond that).
- Runs are listed for 30 days. Deliveries and their attempt logs are listed for 30 days, or as long as the event's body is kept when that is longer.
- Event bodies, which a redelivery needs, are kept by plan: until delivered on Pay as you go, 7 days on Builder, 30 on Pro, 90 on Scale and Enterprise ([How long events are kept](/docs/webhooks#how-long-events-are-kept)).
- Webhook URLs must be `https://` and public: private, local and internal addresses are refused when you save the URL and again on every delivery.

## The monitor object

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | `mon_…` |
| `customId` | string or null | Your own reference. |
| `name` | string or null | A label, up to 80 characters. |
| `sku` | string | The API it runs. It cannot change: make a new monitor instead. |
| `input` | object | The API's input, checked against the API's schema whenever it is saved. It may also carry `maxCredits`, the most one run may cost. |
| `intervalSeconds` | integer | 60 to 2,592,000. |
| `webhookUrl` | string | Where events are sent. |
| `notify` | string | `change` or `always`. |
| `notifyFailures` | boolean | Send `monitor.run.failed` when a run fails. |
| `status` | string | `active` or `paused`. |
| `pausedReason` | string or null | Why we paused it: `failing` when 10 runs in a row failed ([When runs keep failing](#when-runs-keep-failing)). `null` when you paused it, and while it's active. |
| `failingSince` | string or null | When the current run of failures began: the start of the first failed run since the last successful one. `null` when the last counted run succeeded, before any run has counted, and after you resume the monitor. |
| `consecutiveFailures` | integer | Failed runs in a row since the last successful one. `0` after a success and after you resume. The 10th pauses the monitor. |
| `keyId` | string or null | The key the runs act as, or `null` for the workspace. |
| `nextRunAt` | string or null | When the next run is due; `null` while paused. |
| `lastRunAt` | string or null | When the last run started. |
| `lastRunStatus` | string or null | `succeeded`, `failed` or `skipped`. |
| `lastDeliveryStatus` | string or null | Status of the newest delivery: `pending`, `retrying`, `succeeded` or `failed`. |
| `createdAt`, `updatedAt` | string | ISO 8601 times. |

## POST /v1/monitors

`POST https://api.primaryapi.com/v1/monitors`

Auth: API key with run or full access, or a dashboard session (owners, admins, developers)

Creates a monitor; its first run is due at once. The body is strict: unknown fields are rejected.

| Field | Type | Required | Description |
|---|---|---|---|
| `sku` | string | yes | The API to run, for example `instagram.profile`. |
| `input` | object | yes | The API's input, validated like a call's. |
| `intervalSeconds` | integer | yes | 60 to 2,592,000. |
| `webhookUrl` | string | yes | A public `https://` URL, up to 2,048 characters. |
| `notify` | string | no | `change` (default) or `always`. |
| `notifyFailures` | boolean | no | Default `true`. |
| `customId` | string or null | no | Your own reference. |
| `name` | string or null | no | 1 to 80 characters. |
| `keyId` | string or null | no | Dashboard only: the key the runs act as. An API key always uses itself (it may name only its own id). |

**201 Created**: the monitor. Errors:

- `400 invalid_input`: the input does not match the API's schema, an interval is out of range, the webhook URL is not public `https://`, or `keyId` is not a usable key of the workspace.
- `403 restricted_api`.
- `404 not_found`: unknown API.
- `409 custom_id_taken`.
- `422 unprocessable`: 1,000 monitors already.
- `503 service_unavailable`: the API cannot be served right now.

```json title="201 Created"
{
  "id": "mon_01jc8t2v6x0d4f6h8k0m2p4r6t",
  "customId": "crm-account-1042",
  "name": null,
  "sku": "instagram.profile",
  "input": { "username": "natgeo" },
  "intervalSeconds": 3600,
  "webhookUrl": "https://example.com/hooks/primaryapi",
  "notify": "change",
  "notifyFailures": true,
  "status": "active",
  "keyId": "key_01jc8sz2b4d6f8h0k2m4p6r8t0",
  "nextRunAt": "2026-11-09T12:00:00.000Z",
  "lastRunAt": null,
  "lastRunStatus": null,
  "lastDeliveryStatus": null,
  "createdAt": "2026-11-09T12:00:00.000Z",
  "updatedAt": "2026-11-09T12:00:00.000Z",
  "connection": null,
  "pausedReason": null,
  "failingSince": null,
  "consecutiveFailures": 0
}
```

## GET /v1/monitors

`GET https://api.primaryapi.com/v1/monitors`

Auth: API key with run, view or full access, or a dashboard session

The workspace's monitors, newest first. Query: `limit` (1 to 200, default 50), `cursor`, `status` (`active` or `paused`), `sku`, `customId` (exact). **200 OK**: `{ "items": [<monitor>, …], "nextCursor": "…" }`; pass `nextCursor` as `cursor` for the next page ([Pagination](/docs/pagination)).

## GET /v1/monitors/\{id\} and GET /v1/monitors/by-custom-id/\{customId\}

`GET https://api.primaryapi.com/v1/monitors/{id}`

Auth: API key with run, view or full access, or a dashboard session

One monitor, by its id or by your `customId`. **200 OK**: the monitor. `404 not_found` for a deleted monitor, or one of another workspace.

## PATCH /v1/monitors/\{id\}

`PATCH https://api.primaryapi.com/v1/monitors/{id}`

Auth: API key with run or full access, or a dashboard session (owners, admins, developers)

Changes a monitor. Send only what changes: `input`, `intervalSeconds`, `webhookUrl`, `notify`, `notifyFailures`, `customId`, `name`, `keyId` (`null` clears the last three) and `status`. Changing the interval reschedules the next run one new interval after the last run (or at once, if that has passed). Resuming (`"status": "active"`) clears `pausedReason`, `failingSince` and `consecutiveFailures`. **200 OK**: the monitor. Errors as for create.

## DELETE /v1/monitors/\{id\}

`DELETE https://api.primaryapi.com/v1/monitors/{id}`

Auth: API key with run or full access, or a dashboard session (owners, admins, developers)

Deletes a monitor: it stops at once, its `customId` is free again, and deliveries still waiting for a retry are given up. **200 OK**: `{ "id": "mon_…", "deleted": true }`.

## POST /v1/monitors/\{id\}/run

`POST https://api.primaryapi.com/v1/monitors/{id}/run`

Auth: API key with run or full access, or a dashboard session (owners, admins, developers)

Runs the monitor now, charged like a call. **200 OK**: the run, once it has finished. When the API is still working after the usual wait (some APIs take minutes), the answer is **202 Accepted** with `{ "runId", "monitorId", "requestId", "status": "running", "createdAt" }`; the run appears in the runs list when it ends, and `GET /v1/requests/{requestId}` follows the call ([Durable requests](/docs/durable-requests)). `422 unprocessable` while another run of this monitor is in progress.

## POST /v1/monitors/\{id\}/test

`POST https://api.primaryapi.com/v1/monitors/{id}/test`

Auth: API key with run or full access, or a dashboard session (owners, admins, developers)

Sends a `monitor.test` event to the monitor's webhook URL, free. **201 Created**: the delivery after its first attempt, so you see at once whether your endpoint answered. A failed test is retried like any delivery.

## GET /v1/monitors/\{id\}/runs

`GET https://api.primaryapi.com/v1/monitors/{id}/runs`

Auth: API key with run, view or full access, or a dashboard session

The monitor's runs, newest first (`limit`, `cursor`). A run is listed once it has ended.

| Field | Type | Description |
|---|---|---|
| `id` | string | `mrun_…` |
| `monitorId` | string | |
| `requestId` | string or null | The call it made, the same id as in `GET /v1/requests/{id}`; `null` for a skipped run. |
| `status` | string | `succeeded`, `failed` or `skipped`. |
| `reason` | string or null | Why it was skipped or failed. |
| `credits` | integer | What the run cost. |
| `items` | integer | Billable results, as in the run envelope. |
| `changed` | boolean | Whether the output differs from the last successful run. |
| `notified` | boolean | Whether the run sent a webhook. |
| `manual` | boolean | Started with Run now. |
| `createdAt` | string | When the run started. |

## GET /v1/monitors/\{id\}/deliveries

`GET https://api.primaryapi.com/v1/monitors/{id}/deliveries`

Auth: API key with run, view or full access, or a dashboard session

The monitor's webhook deliveries, newest first (`limit`, `cursor`). Fields: `id` (`whd_…`), `monitorId`, `runId`, `eventId`, `eventType`, `url`, `status` (`pending`, `retrying`, `succeeded`, `failed`), `attempts` (made so far, up to 11), `nextAttemptAt`, `lastResponseStatus` (your endpoint's HTTP status), `lastError` (a short reason for the last attempt), `createdAt` and `deliveredAt`. Redelivering is on the [Webhooks](/docs/webhooks#redeliver) page.

## GET /v1/monitors/\{id\}/deliveries/\{deliveryId\}

`GET https://api.primaryapi.com/v1/monitors/{id}/deliveries/{deliveryId}`

Auth: API key with run, view or full access, or a dashboard session

One delivery with its `attemptLog`: every attempt's start time, duration, your endpoint's status or why it failed, the first 1,024 bytes of its response and when the next attempt is due ([The attempt log](/docs/webhooks#the-attempt-log)). **200 OK**: the delivery. `404 not_found` for a delivery of another monitor or workspace.
