Monitors
A monitor watches one competitor surface (pricing page, blog index, changelog, etc.) on a cadence. Checks detect changes and create interpreted change records.
List monitors
GET /v1/monitors?workspace_id=:id
| Query param | Required | Description |
|---|---|---|
workspace_id |
yes | Workspace to scope monitors |
competitor_id |
no | Filter to one competitor |
curl "https://api.competiflow.com/v1/monitors?workspace_id=42" \
-H "Authorization: Bearer $COMPETIFLOW_API_KEY"
Response (200 OK):
{
"monitors": [
{
"id": 101,
"competitor_id": 7,
"name": "Pricing",
"url": "https://example.com/pricing",
"monitor_type": "pricing",
"cadence": "daily",
"status": "active",
"min_severity": "low",
"proxy_kind": "datacenter",
"last_checked_at": "2026-07-14T06:00:00Z",
"next_check_at": "2026-07-15T06:00:00Z",
"consecutive_failures": 0,
"last_run": {
"id": 5001,
"status": "succeeded",
"finished_at": "2026-07-14T06:00:05Z"
}
}
]
}
Returns 422 workspace_required if workspace_id is missing or invalid.
Get monitor
GET /v1/monitors/:id
Includes extraction_schema, pre_steps, and discovery_source in addition to summary fields.
GET /v1/monitors/:id?include=capture,capture_markdown
Optional include loads the latest successful capture for this monitor (the current baseline page).
| Token | Description |
|---|---|
capture |
Extracted fields from the latest check |
capture_markdown |
Page markdown from the latest check |
Create monitor
POST /v1/monitors
| Body field | Type | Required | Description |
|---|---|---|---|
competitor_id |
integer | yes | Parent competitor |
url |
string | yes | Page URL to watch |
monitor_type |
string | yes | pricing, blog, changelog, docs, homepage, or generic |
cadence |
string | no | Default daily |
Queues a baseline check on create.
Update monitor
PATCH /v1/monitors/:id
Send any of: url, monitor_type, cadence, status, min_severity. status accepts active or paused.
status: paused stops scheduled checks but keeps history. DELETE removes the monitor, its snapshots, and its changes.
Delete monitor
DELETE /v1/monitors/:id
Removes the monitor and all associated check runs, snapshots, and changes. Frees one monitor slot on your plan.
Trigger check
POST /v1/monitors/:id/check
Runs an on-demand check. Uses one check. The check runs asynchronously; read results via Changes shortly after.
Response (202 Accepted):
{
"status": "queued",
"monitor_id": 101
}
| Status | Code | When |
|---|---|---|
| 409 | discovery_in_progress |
Workspace discovery still running |
| 429 | refresh_throttled |
Monitor checked too recently |
Status and health
status is either active (scheduled on its cadence) or paused (not scheduled). Read the health of an active monitor from two fields:
| Field | Meaning |
|---|---|
consecutive_failures |
Count of failed checks in a row. 0 means the last check succeeded. |
last_run.status |
Outcome of the latest check: succeeded, no_change, changed, failed, running, or pending. |
Failed checks (timeouts, blocks) are not billed. Successful runs debit one check each.