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.
Last updated
On this page
- How a monitor works
- Credits
- Skipped runs
- When runs keep failing
- Change detection
- Your own ids
- Keys and who can do what
- Pause, run now and test
- Limits
- The monitor object
- POST /v1/monitors
- GET /v1/monitors
- GET /v1/monitors/{id} and GET /v1/monitors/by-custom-id/{customId}
- PATCH /v1/monitors/{id}
- DELETE /v1/monitors/{id}
- POST /v1/monitors/{id}/run
- POST /v1/monitors/{id}/test
- GET /v1/monitors/{id}/runs
- GET /v1/monitors/{id}/deliveries
- GET /v1/monitors/{id}/deliveries/{deliveryId}
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.
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 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 sendmonitor.run.failedwhilenotifyFailuresis 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).
- 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). 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. |
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), 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
2xxfor 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) andfailingSince(when the first of them started). A success sets them back to0andnull. - 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, itsmonitor.run.failedevent carriesmonitorPaused: { "reason": "failing", "failingSince": "…", "consecutiveFailures": 10 }(Webhooks). WithnotifyFailuresoff, 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 clearspausedReason,failingSinceandconsecutiveFailures, 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) 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
inputstarts over: the next successful run counts as a first run. - Every run reports
changedeither way, also withnotify: "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 indetails.monitorId. Deleting a monitor frees itscustomId. - Find a monitor by it with
GET /v1/monitors/by-custom-id/{customId}(URL-encode it:crm/42becomescrm%2F42) or filter a list withGET /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
runkey can change, run and delete only the monitors that run with it; afullkey can change any monitor of the workspace; aviewkey 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 clearspausedReason,failingSinceandconsecutiveFailures.POST /v1/monitors/{id}/runruns 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 is422 unprocessable: try again when it has finished.POST /v1/monitors/{id}/testsends amonitor.testevent to the webhook URL. It is free and runs nothing.
Limits
- A workspace keeps at most 1,000 monitors that are not deleted (
422 unprocessablebeyond 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).
- 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). 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
api.primaryapi.com/ v1/ monitorsAuth: 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 publichttps://, orkeyIdis 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.
{
"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
api.primaryapi.com/ v1/ monitorsAuth: 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).
GET /v1/monitors/{id} and GET /v1/monitors/by-custom-id/{customId}
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}
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}
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
api.primaryapi.com/ v1/ monitors/ {id}/ runAuth: 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). 422 unprocessable while another run of this monitor is in progress.
POST /v1/monitors/{id}/test
api.primaryapi.com/ v1/ monitors/ {id}/ testAuth: 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
api.primaryapi.com/ v1/ monitors/ {id}/ runsAuth: 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
api.primaryapi.com/ v1/ monitors/ {id}/ deliveriesAuth: 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 page.
GET /v1/monitors/{id}/deliveries/{deliveryId}
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). 200 OK: the delivery. 404 not_found for a delivery of another monitor or workspace.