Heartbeats & API monitoring

Per heartbeat you get a unique URL — add a curl call at the end of your script/cron. Missed ping within the grace window = alert.

Two expectation models: a fixed interval (expected_interval_seconds, 60s to 24h, default 300s) OR a full cron expression (schedule, e.g. “0 3 * * *”) with its own timezone (timezone). Cron expressions are validated server-side; a timezone, if set, must be a valid IANA zone. On top sits a grace window (grace_period_seconds, 0 to 3600s, default 60s) as tolerance. If the ping is missing by deadline = next due time + grace, an alert fires. With a cron schedule the next due time is computed from the cron expression in the monitor timezone, otherwise from last ping + interval.

A monitor moves through the states active, missed, failed and paused. The last ping is stored with a timestamp; if it is missing by the deadline, the monitor is set to “missed” and a heartbeat_missed alert fires. Paused monitors raise no alerts. If a monitor stays “missed” for more than 7 days (long-term down without any reaction), a cleanup routine automatically sets it to “paused” and resolves stale heartbeat alerts — keeping the alert feed clean.

You can append metrics to the ping URL: items (records processed, alias: processed), exit_code (0 = ok, anything else = failure), duration_ms (runtime in milliseconds), output or msg (a short plain-text note) and status=ok|fail. All parameters are optional and stored per run.

You don't have to compute the duration yourself: ping /start at the job's beginning and /ping at the end — XICTRAQ takes the difference as runtime. Alternatively, pass duration_ms directly. The latest runtime shows up as last_duration_ms in the monitor overview.

Instead of just letting the ping go missing, your script can report a failure right away: a GET on /fail sets the monitor to status “failed” and fires a heartbeat_failed alert immediately — you do not have to wait out the grace window. Optionally append ?msg=… as the failure reason, ?exit_code=… and ?items=…. The next healthy /ping auto-recovers the monitor.

With duration_anomaly_auto, XICTRAQ learns your job's normal runtime per hour-of-week (mean + 3σ over a rolling window) and alerts when a run falls clearly outside the band — e.g. “ran 4× longer than usual on Mondays at 03:00”. Opt-in per heartbeat. Independently of it, the static threshold duration_threshold_ms (in milliseconds) always applies: if you do not set it yourself, a default of 60000 ms (60 seconds) is used, above which a run is alerted as slow; 0 switches the static threshold off. This avoids rigid thresholds for jobs with fluctuating load.

Enable expect_output when a run must produce output or items. Optionally set min_items as a minimum count. If the job then pings with items=0 (or below the minimum), XICTRAQ treats the run as an empty run and alerts — even when the exit code was 0. Exactly the “backup completed but saved 0 files” case.

GET /api/heartbeat/{id}/history returns the latest runs as JSON — per run kind (ping | start | fail), duration_ms, exit_code, items and created_at. Handy for pulling runtime trends or item counts into your own dashboards. In the overview these are mirrored by the monitor fields last_duration_ms, last_items, last_exit_code, last_anomaly_at and last_anomaly_reason.

Freely combinable per endpoint. JSON schema can be defined in the UI or filtered via JSONPath selector (“response.users[*].email”). Regex matches in the body possible.

Per endpoint you can set arbitrary HTTP headers — e.g. Authorization: Bearer eyJ..., X-API-Key: ... or basic-auth values. Headers are stored server-side and sent with every request. Static tokens work directly. For OAuth flows with short-lived tokens, combine API monitoring with a browser monitor (login flow + assert).

Each endpoint has a Run-now button (POST /api-endpoints/{id}/run) that triggers an immediate check independent of the cron. Useful after a deploy or while an alert is open to verify whether the issue is fixed — without waiting for the next interval.

Instead of a single request you can chain up to 10 steps. Each step can extract values from its response (JSON path, header or regex) and reuse them via {{variable}} in the URL, headers or body of the next step — e.g. a token from the login step. Conditional execution (run_if) skips steps when a variable is missing; stop_on_fail halts the chain on the first failure. This monitors real auth-protected workflows, not just open health endpoints.

Store a JSON schema per endpoint and XICTRAQ additionally validates the response body against this contract — catching silent schema changes (“contract drift”): HTTP 200, but a required field is missing, a type changed or a value leaves its allowed range. If the body violates the schema, the run counts as failed and is treated like a down for alerting: if the next check fails too, the same alert goes out. A JSON-schema subset is supported: type, required, properties, items (recursive), enum, minimum/maximum, minLength/maxLength and format (email, uri, date-time). If no schema is stored or the response is not valid JSON, the contract check is skipped — so it never degrades a run by mistake.

Per endpoint you pick the method (GET, POST, PUT, PATCH, DELETE, HEAD), request body, check interval and timeout (1–30s, default 10s). The minimum interval depends on the plan: 300s on Starter, 60s on Business, 30s on Agency — a shorter value is automatically raised to the plan minimum. A cron checks every 30 seconds which endpoints are due and runs up to 200 checks per pass. The last 500 check results per endpoint are kept as history (HTTP code, response time, assertion results), retrievable via GET /api-endpoints/{id}/history.