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 a fraction of a second.
||Report task is running.|
||Report task is complete.|
||Report task has failed.|
||Pause monitoring for given <hours>|
"My Job Is Running"
/run endpoint to report that your task is running. In the simplest implementation this
is done by adding a curl request before your command execution directly within your crontab. For a cleaner integration, use
Note: To support 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 Job Completed Successfully"
/complete endpoint to report that your task has completed successfully. In the simplest implementation this
is done by chaining a curl request to your command execution directly within your crontab. For a cleaner integration, use
Optionally send up to 1000 chars of context data as a url-encoded
"My Job Has Failed"
/fail endpoint to report that your task has failed. In the simplest implementation this
is done by pinging Cronitor after the job exits with an error code, using an
|| operator. For a cleaner integration, use
CronitorCLI. 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.
"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 curl or 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.
Pro Tip: 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.