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`.
`grace_seconds`	int	`0`	Extra seconds after the interval before a missing ping alerts, `0` to `86400`. See how lateness is evaluated.
`group_notification_ids`	uuid[]	default group	Notification groups to fire on state change. Maximum 10, no duplicates, must belong to your account. On create, omitting it (or sending `null`) attaches your account’s default group; `[]` notifies no one.
`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.
One optional segment after the ID says what happened:

Path	Records	Effect
`/{account_id}/{cron_job_id}`	`ping`	A successful run.
`.../start`	`start`	A run began. Not a ping: it does not reset lateness, and it does not update `last_received_at`.
`.../fail`	`fail`	A failed run. The check is evaluated right away and goes down.
`.../{exit_code}`	`ping` for `0`, else `fail`	An exit code from 0 to 255, kept on the receipt.

Any other segment is a 400.

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.
`kind`	`ping`, `start` or `fail`.
`exit_code`	The exit code sent in the path, if any.
`run_ms`	On a ping or failure that directly follows a start: how long the run took. Returned by `GET /cron/job/{job_id}/recent` only.

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

How lateness is evaluated

An active check that is up goes down when no finished-run ping arrives within check_interval_seconds plus grace_seconds of the newest of its last finished-run ping, its created_at and its last resume. Every check is compared with that deadline once a minute, so the alert follows within about a minute of it. A ping that arrives late but inside the grace counts for that run, and the next deadline is measured from it. A successful ping on a failed check is evaluated right away and brings it back to success. The grace period guide has a worked example.

Changing check_interval_seconds or grace_seconds applies from the last ping at once: the check goes down right away if its last ping is already outside the window, and comes back up if its last ping was a success that fits it. Resuming a paused check starts the wait over from the resume.

Only finished runs count: a start is ignored here. When the newest finished run is a fail, the check fails even though it arrived in time, and the alert says the job reported a failure (with the exit code, if sent) rather than that no ping arrived. A fail on an active check that is up is evaluated at once.

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.