Cron check reference

The full request/response schema is in the auto-generated API Reference. This page is the human-readable cheat sheet for POST /cron/job and PUT /cron/job/{cron_job_id}.

Request settings

Field	Type	Default	Description
`friendly_name`	string	none	Display name shown in the dashboard. 1 to 99 characters.
`check_interval_seconds`	int	required	Expected interval between pings. Must be at least `60` and a multiple of `60`.
`group_notification_ids`	uuid[]	none	Notification groups to fire on state change. Maximum 10, no duplicates, must belong to your account.
`tags`	string[]	none	Free-form tags. Used for grouping and maintenance-window matching.
`state`	enum	`active`	Update only. `active` or `paused`. Paused checks stop evaluating and alerting.

Read-only fields

Field	Type	Description
`id`	uuid	Cron check ID. Part of the ping URL.
`account_id`	uuid	Owning account. Part of the ping URL.
`current_status`	enum	`success` or `failed`.
`last_received_at`	rfc3339 \| null	Most recent ping received.
`last_checked_at`	rfc3339 \| null	Most recent lateness evaluation.
`last_status_change_at`	rfc3339 \| null	When `current_status` last transitioned.
`created_at`	rfc3339	When the check was created.
`group_notifications`	object[] \| null	Full notification-group objects resolved from `group_notification_ids`.
`service_id`	uuid \| null	Service this check belongs to.

The ping endpoint

POST https://ping.siteqwality.com/{account_id}/{cron_job_id}

No API key. The URL itself is the credential; treat it like a secret.
Only the path is validated (both segments must be valid UUIDs belonging to an existing check). The HTTP method is not checked; POST is the convention.
Each received ping is recorded with:

Field	Description
`id`	Unique receipt ID.
`cron_job_id`	The check that was pinged.
`created_at`	Server-side receive timestamp.
`receiving_address`	Caller IP, from `X-Forwarded-For`.
`receiving_headers`	The full request-header map. Useful for identifying which host or runner pinged.

Receipts are queryable via GET /cron/job/{job_id}/recent.

How lateness is evaluated

Each cron check is evaluated on its own schedule, at the same cadence as check_interval_seconds. At each evaluation the check fails when the newest ping is older than check_interval_seconds, and also when no ping has ever been received. Because evaluation runs at the same cadence as the expected pings, a missed ping is detected between one and two intervals after the last successful ping, depending on how the two schedules line up. The next received ping flips the status back to success at the following evaluation.

Status-transition events

GET /cron/job/{job_id}/events returns failure windows:

Field	Description
`id`	Event ID.
`cron_job_id`	The check.
`created_at`	When the event row was written.
`started_at`	When the failure window opened.
`ended_at`	When it closed, `null` while still failing.
`ended_by_cron_job_received_id`	The receipt that ended the failure, when it was ended by a ping.

Endpoints

Method	Path	Purpose
`POST`	`/cron/job`	Create.
`GET`	`/cron/job/{cron_job_id}`	Fetch one check.
`PUT`	`/cron/job/{cron_job_id}`	Update (partial).
`DELETE`	`/cron/job/{cron_job_id}`	Delete.
`GET`	`/cron/jobs`	List.
`GET`	`/cron/job/{job_id}/recent`	Recent ping receipts.
`GET`	`/cron/job/{job_id}/events`	Status-transition events.
`GET`	`/cron/job/{job_id}/uptime_percentage`	Uptime percentage and incident count for a date range.