The Ping API is used to send monitoring events from your system to Cronitor. It's the core integration mechanism for job and event/heartbeat monitoring.
To understand this API we must look at two key aspects, the Resources that is exposes and the Telemetry Events that it supports.
The Ping API exposes two resources for sending telemetry events—important events that occur in your system—to Cronitor.
The differences between these resources are the types of unique identifiers that they accept, and the level of security they provide.
The Ping API exposes two resources for sending telemetry information to Cronitor about events that occur in your system, e.g. that a cron job has started or crashed.
The differences between them are the types of unique identifiers that they accept, and the level of security they provide.
Cronitor assigns a globally unique identifier to every monitor. These
:monitorIds can be used to send telemetry events to the
Monitor resource, e.g.
You can provide your own unique identifier for a monitor when pinging the
Organization resource, e.g.
If a monitor does not exist for your supplied ID, a new monitor will be created automatically. This allows you to use either Cronitor's unique ID or your own.
Tip:For additional security, you can disable the
Monitor resource and Cronitor will only accept pings using the
Organization resouce containing both your organization's
Ping API Key and either your own unique identifier, or the Cronitor globally unique identifier.
There are two classes of monitors that use the Ping API, Jobs and Events. The telemetry events you choose will be based on your needs.
||Report job is running||Jobs|
||Report job is complete||Jobs|
||Report an event occurred private beta||Events|
||Report a failure/error||Jobs Events|
||Manually reset a monitor to a healthy state||Jobs Events|
||Pause alerting for given <hours>||Jobs Events|
"Job Is Running"
/run endpoint to report that your job is running.
- For backwards compatibility, requests made to the ping URL without specifying an endpoint are treated as
/runping will place your job into a running state on your dashboard.
"Job Completed Successfully"
/complete endpoint to report that your job has completed successfully.
"Event Has Occurred"
/tick endpoint to report that an event you wish to monitor occurred.
"Job Has Failed" or "Error Has Occurred"
/fail endpoint to report that your job has failed. When a failure
is reported you will be alerted immediately.
- 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 job is running and failing rapidly, alerts are batched to one per minute.
"Monitor 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 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 2000 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 Ping API authentication is enabled.|
||complete, fail||Exit code returned from the task|
||complete, fail||Total runtime as float|
Unlike our Monitor API, Ping
API endpoints do not require authentication by default. As an additional level of security, you can require all ping requests use the
Organization resource which requires a Ping API key to access.
To enable authentication go to your account settings page.
Once all pings include the key, activate the checkbox that says "Require Ping API Authentication".
# Example using the Organization resource to send authenticated requests curl -m 5 https://cronitor.link/ping/a9ff42ad0abc1/d3x0c1/run
Tip:If you have already integrated some tasks with Cronitor, update your integrations to use the
Organization resource before enabling this!
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.
In order to prevent users from accidentally flooding the Ping API (and potentially disrupting service for other users), Cronitor imposes rate limits on the number of requests that can be made to the Ping API. Requests over the limit will receive an
HTTP 429 status code.
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