To determine the status of your cron job and heartbeat monitors, Cronitor must know when your jobs and tasks run and complete. To report these and other events, each monitor you create is given a unique ping API with corresponding endpoints. A ping is a simple HTTP request with no payload that returns no content. Most commonly ping requests are made using curl or CronitorCLI and are completed in under a second.
||Report task is running|
||Report task is complete|
||Report task has failed|
||Reset your monitor to a healthy state|
||Pause monitoring for given <hours>|
"My Task Is Running"
/run endpoint to report that your task is running.
Note: For backwards compatibility, requests made to your ping URL without specifying an endpoint are
--data-urlencodeto url encode your msg when using curl.
/runping will place your task into a running state on your dashboard.
"My 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
"My 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 failing status 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.
"My Monitor is OK"
/ok endpoint to reset your monitor back to passing status until the next fail event or rule violation occurs.
/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 may receive an alert immediately if any of your
monitors remain in 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
||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
when making tracking requests or pausing your monitor.
To enable Ping API 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_keyto 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.
Every integration has constraints. If it's more important to be brief than explicit, you can use a 1 character
abbreviated short form of each endpoint:
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. We plan to continue supporting ping requests on cronitor.io indefinitely but if you are currently pinging cronitor.io, you may experience faster ping times by switching to cronitor.link.
Note: 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
To more clearly align rules and endpoints,
/e ping endpoints are deprecated and
will be mapped internally to
/complete, respectively. Similarly, you may have
been given a URL without any endpoint specified. This URL was always treated as
a /b "begin" ping. We've deprecated these requests and discourage them. To maintain backwards
compatibility we will continue to map these requests to /run.
If you are an early Cronitor user with a "not run in" rule and you modify your integration to ping
/run before your job and
/complete after, you may want to change your "not run in" rules to "not completed in". A "not run in" rule uses /run pings, which you will now send before the job runs. A "not completed in" rule uses the
/complete pings that will only be sent if your job completes successfully.