Skip to content
Gridlode
Docs · Monitors

Monitors, change history and alerts

A monitor re-runs one engine on a schedule, keeps a snapshot of the values you care about, and records an event whenever they change or a condition starts to hold. Events go to your email and, if you set one, a signed webhook. Each check is billed like a normal request to that engine, and failed checks are free. You can also manage monitors in the dashboard.

Create a monitor from a template

POST /v1/monitors
curl -X POST "https://api.gridlode.com/v1/monitors" \
  -H "Authorization: Bearer $GRIDLODE_KEY" -H "Content-Type: application/json" \
  -d '{
    "template": "ssl_expiry",
    "target": "example.com",
    "options": { "days": 21 },
    "interval_minutes": 1440,
    "webhook_url": "https://example.com/hooks/gridlode"
  }'
templateWatchesEngineWhat it does
domain_expiryDomain registrationdomain.rdapExpiry date, registrar, status and name servers. Alerts when fewer than options.days (default 30) remain.
ssl_expirySSL certificatedomain.sslIssuer, validity and expiry. Alerts when the certificate turns invalid or fewer than options.days (default 14) remain.
dns_changeDNS recordsdomain.dnsEvery change to A, AAAA, MX, NS, TXT, CNAME and CAA records. Checks every 6 hours by default.
email_securityEmail securitydomain.email_securitySPF, DMARC, MX provider and grade. Alerts below options.min_score (default 60).
page_changePage contenturl.markdownAny change to the readable text of a page. options.keyword also alerts when the page mentions a word.
serp_rankSearch rankingserp.bingPosition of options.domain in the top 50 Bing results for a keyword. Alerts outside options.max_position (default 10).
app_store_reviewsNew App Store reviewsreviews.app_storeNew reviews of an iOS app (target: the numeric app ID or App Store URL; options.country, default us).
google_play_reviewsNew Google Play reviewsreviews.google_playNew reviews of an Android app (target: the package name or Play Store URL).
new_reviewsNew reviewsreviews.trustpilotNew Trustpilot reviews and TrustScore changes. Alerts below options.min_score (default 3.5).

interval_minutes is at least 60 and defaults to the template's schedule. The first check runs within a minute and records a baseline. GET https://api.gridlode.com/v1/monitors/templates lists the templates.

Custom monitors

Any engine can be monitored. Give its params, the watch expressions to compare, and optional conditions:

Custom monitor body
{
  "name": "Competitor tech stack",
  "engine": "domain.tech",
  "params": { "domain": "competitor.com" },
  "watch": ["technologies[].name", "@count(technologies)"],
  "conditions": [{ "path": "@count(technologies)", "op": "gt", "value": 40, "label": "More than 40 technologies" }],
  "interval_minutes": 10080
}
  • a.b.c: a value in the engine output (array indexes allowed, like organic_results.0.link).
  • a[].b: the list of b across array a, compared as a set.
  • @hash(path): a fingerprint of long text such as page markdown.
  • @rank(array, field, needle): the position of the first item whose field contains the needle.
  • @ids(array, field): item IDs; changes report how many were added or removed.
  • @count(path): the length of an array.

Condition operators: lt, lte, gt, gte, eq, ne, contains, not_contains, is_true, is_false and days_until_lt (for dates). An alert fires once when a condition starts to hold, and a recovered event follows when it stops.

Manage monitors

  • GET /v1/monitors and GET /v1/monitors/{id}: list and inspect.
  • PATCH /v1/monitors/{id}: change name, status (active or paused), interval_minutes, notify_email or webhook_url (a new URL returns a new secret).
  • DELETE /v1/monitors/{id}: delete the monitor and its history.
  • POST /v1/monitors/{id}/run: check now.
  • GET /v1/monitors/{id}/events, GET /v1/monitors/events: changes, alerts, recoveries and errors.
  • GET /v1/monitors/{id}/history: every distinct snapshot with its time, for WHOIS, DNS and SSL history.

Monitors pause themselves when your balance can't cover a check or your monthly spend cap is reached. Resume them after topping up.

Webhook events

We POST {"event":"monitor.change","monitor":{...},"summary":"...","changes":[{"path","before","after"}]}. Events are monitor.change, monitor.alert, monitor.recovered and monitor.error. The X-Gridlode-Signature header is signed exactly like bulk job webhooks.