The Ping API is used to monitor the execution of a backend task (cron job, scheduled task, daemon, etc).
Each monitor you create is assigned a unique URL that exposes the Ping API. An example URL looks like this
||Report task is running|
||Report task is complete|
||Report task has failed|
||Reset your monitor to a healthy state|
||Pause monitoring for given <hours>|
"Task Is Running"
/run endpoint to report that your task is running.
- For backwards compatibility, requests made to the ping URL without specifying an endpoint are treated as
/runping will place your task into a running state on your dashboard.
"Task Completed Successfully"
/complete endpoint to report that your task has completed successfully.
Optionally send up to 1000 chars of context data as a url-encoded
"Task Has Failed"
/fail endpoint to report that your task has failed. When a failure
is reported you will be alerted immediately. Optionally send up to 1000 chars of context data as a URL-encoded
- After a
/failping your monitor will remaining in a failing state until the next
- After a failure, Cronitor will temporarily suppress other alerts to avoid duplicates.
- When your task is running and failing rapidly, alerts are batched to one per minute.
"Task is OK"
/ok endpoint to reset your monitor back to a passing status until the next fail event or rule violation occurs.
- The primary use case for OK is to reset a monitor after some type of human intervention. It is not required to reset a monitor after a recovery.
/okping will not trigger recovery alerts.
- When monitoring is resumed after a pause, an
/okping is automatically sent to ensure you are not sent false alarms.
"No alerts should be sent for __ hours"
/pause endpoint to temporarily pause monitoring and alerts for this monitor. An <hours> integer is required.
To unpause instantly, use "0" hours. After the pause expires you will receive an alert if the monitor is still in a failing state.
Note: This endpoint is built for use from a browser and returns an HTML response. Clients can ignore the body and trust the response code.
- You can permanently pause a monitor from your dashboard, or by specifying a large number of <hours>, e.g.
- Alert emails always include links to pause monitoring for an hour or day to prevent repeated alerts
Tip: If you prefer brevity you can use a 1 character abbreviated short form of each endpoint:
||run, complete, fail||A url-encoded message, up to 1000 chars|
||run, complete, fail||The name of the server sending this request|
||run, complete, fail||A unique user-supplied ID to collate related pings|
||run, complete, fail, pause||Ping API key. Required if "Authenticate ping requests" is enabled.|
||complete, fail||Exit code returned from the task|
||complete, fail||Total runtime as float|
Unlike our Monitor API, your ping
API endpoints do not require authentication by default. You can enable additional security by requiring an
query parameter when making pinging or pausing your monitor.
To enable authentication go to your account settings page. If you have already integrated some tasks with Cronitor, add your Ping API key to existing ping requests before proceeding.
Once all pings include the key, activate the checkbox that says "Authenticate ping requests". Once you have enabled this feature any requests without a valid
auth_key parameter will be ignored.
# Example using your auth_key to ping your monitor's complete endpoint curl -m 5 https://cronitor.link/d3x0c1/complete?auth_key=your_ping_api_key
There are a few additional points on security and privacy to consider:
https://). Cronitor supports unencrypted pings because some use-cases demand it, but unless yours is one, you should use SSL. Requests made using SSL are private: the URL is encrypted and protected in transit. As an added benefit, SSL prevents unwanted caching that could occur between your system and Cronitor.
If you have a server that cannot make outbound HTTP requests, or you have a monitoring use case where you would like to use email to notifiy Cronitor, you can do so by sending emails to
To call different monitor events append the event name with a
+ as shown below.
Ping endpoints will accept
requests. At this time, all POST bodies are discarded.
Originally, ping URLs were hosted on the cronitor.io domain. To segregate ping traffic, we launched the cronitor.link domain in February, 2015. This is a specially tuned cluster of ping collectors optimized for huge burts of ping traffic (think midnight UTC). We plan to support pings on cronitor.io indefinitely, but do not suggest using it as your primary ping domain.
Unencrypted (e.g. http://) pings are only accepted on cronitor.link. Unencrypted pings sent to cronitor.io will receive a 301 redirect response pointing to https://cronitor.io