Content Monitoring

Previous Next

Content monitors watch a URL on a schedule and alert when rules are met. Each user can keep up to 50 active monitors.

  • Status values: active, paused, disabled
  • Rule types: any_change, text_appeared, text_disappeared, status_code_change
  • Rule config: text rules require needle (string, max 512) and optional caseSensitive (bool); other rules use an empty config.
  • Frequency: 5–1440 minutes
  • Backends: httpx, playwright, scrapling

Create a monitor

POST /content-monitors (auth required)

{
  "name": "Homepage watch",
  "url": "https://example.com",
  "backend": "playwright",
  "frequencyMinutes": 30,
  "rule": {
    "type": "text_appeared",
    "config": { "needle": "Shipping", "caseSensitive": false }
  }
}
  • name is optional; defaults to the URL.
  • Exceeding the active limit returns 422 with detail: "monitor_limit_reached".

Response (201) includes monitor metadata:

{
  "id": "uuid",
  "name": "Homepage watch",
  "url": "https://example.com",
  "backend": "playwright",
  "status": "active",
  "frequencyMinutes": 30,
  "rule": { "type": "text_appeared", "config": { "needle": "Shipping", "caseSensitive": false } },
  "nextRunAt": "2024-01-01T12:00:00Z",
  "lastRunAt": null,
  "lastChangeAt": null,
  "lastChangeSummary": null,
  "lastSnapshot": null,
  "consecutiveFailures": 0,
  "createdAt": "2024-01-01T11:00:00Z",
  "updatedAt": "2024-01-01T11:00:00Z"
}

Update a monitor

PATCH /content-monitors/{id} (auth required)

  • Fields are optional: name, frequencyMinutes, status (active|paused|disabled), rule (same shape as create).
  • Response mirrors the show endpoint and includes diagnostics (lastErrorCode, lastErrorMessage).

List monitors

GET /content-monitors (auth required)

Query params: status, backend, q (name/URL contains), page, perPage (max 100), sort (nextRunAt|updatedAt|createdAt), dir (asc|desc).

Returns a paginated list with scheduling info and last snapshot summaries.

Get a monitor

GET /content-monitors/{id} (auth required)

Returns the monitor plus diagnostics (lastErrorCode, lastErrorMessage).

Monitor runs

  • GET /content-monitors/{id}/runs?limit=20 — returns the monitor and recent runs (limit 1–100).
  • POST /content-monitors/{id}/runs — triggers a run. Optional body {"force": true} to run immediately; otherwise uses the scheduled time.

Run statuses: pending, running, succeeded, failed, triggered (change detected), skipped.

Run payload example:

{
  "id": "run-id",
  "monitorId": "monitor-id",
  "status": "triggered",
  "changeDetected": true,
  "changeSummary": "text appeared: Shipping",
  "scrapeId": "scrape-id",
  "statusCode": 200,
  "errorCode": null,
  "errorMessage": null,
  "scheduledAt": "2024-01-01T12:00:00Z",
  "startedAt": "2024-01-01T12:00:05Z",
  "completedAt": "2024-01-01T12:00:20Z",
  "snapshotBefore": { "hash": "abc", "preview": "...", "statusCode": 200, "contentLength": 12034, "capturedAt": "..." },
  "snapshotAfter": { "hash": "def", "preview": "...", "statusCode": 200, "contentLength": 12050, "capturedAt": "..." }
}
Scraping Errors