Ping API

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.

Ping API endpoints

Endpoint Description
/run Report task is running
/complete Report task is complete
/fail Report task has failed
/pause/<hours> Pause monitoring for given <hours>

/run

"My Task Is Running"

Ping your /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 CronitorCLI.

Note: To support backwards compatibility, requests made to your ping URL without specifying an endpoint are treated as /run pings.

Pro Tips:
  • Use --data-urlencode to url encode your msg when using curl.
  • A /run ping will place your task into a running state on your dashboard.

/complete

"My Task Completed Successfully"

Ping your /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 CronitorCLI. Optionally send up to 1000 chars of context data as a url-encoded ?msg param.

/fail

"My Task Has Failed"

Ping your /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 ?msg param.

Pro Tips:
  • After a /fail ping your monitor will remaining in failing status until the next /complete
  • 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.

/pause/<hours>

"No alerts should be sent for __ hours"

Ping your /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.

Pro Tips:
  • You can permanently pause a monitor from your dashboard, or by specifying a large number of <hours>, e.g. /pause/100000
  • Alert emails always include links to pause monitoring for an hour or day to prevent repeated alerts

Optional querystring params

Param Endpoints Description
msg run, complete, fail A url-encoded message, up to 1000 chars
host run, complete, fail The name of the server sending this request
series run, complete, fail A unique user-supplied ID to collate related pings
auth_key run, complete, fail, pause Ping API key. Required if "Authenticate ping requests" is enabled.
status_code complete, fail Exit code returned from the task
duration complete, fail Total runtime as float

Security and Privacy Concerns

Unlike our Monitor API, your ping API endpoints do not require authentication by default. You can enable additional security by requiring an auth_key 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_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:

  • Always use SSL (eg 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.
  • While your unique ping URL might look like it's just a plain hash, there is an embedded checksum. This gives us the ability to detect and filter unwanted traffic. Even clever systems have vulnerabilities, but our security is enhanced by being an uninteresting target.

Shortened Endpoint Aliases

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: /r, /c, /f and /p.

Accepted Methods

Ping endpoints will accept GET, POST and HEAD requests. At this time, all POST bodies are discarded.

Ping URLs on the cronitor.io hostname

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

Deprecated Endpoints

To more clearly align rules and endpoints, /b and /e ping endpoints are deprecated and will be mapped internally to /run and /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.