API

Ping API

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 https://cronitor.link/d3x0c1.

Cronitor provides both a CLI as well as language-specific SDKs for integrating with the Ping API. curl and PowerShell are also popular choices.

Ping API Endpoints

Endpoint Description
/run Report task is running
/complete Report task is complete
/fail Report task has failed
/ok Reset your monitor to a healthy state
/pause/<hours> Pause monitoring for given <hours>

/run

"Task Is Running"

Ping the /run endpoint to report that your task is running.

Notes:
  • For backwards compatibility, requests made to the ping URL without specifying an endpoint are treated as /run pings.
  • A /run ping will place your task into a running state on your dashboard.

/complete

"Task Completed Successfully"

Ping the /complete endpoint to report that your task has completed successfully. Optionally send up to 1000 chars of context data as a url-encoded ?msg param.

/fail

"Task Has Failed"

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

Notes:
  • After a /fail ping your monitor will remaining in a failing state 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.

/ok

"Task is OK"

Ping the /ok endpoint to reset your monitor back to a passing status until the next fail event or rule violation occurs.

Notes:
  • 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.
  • An /ok ping will not trigger recovery alerts.
  • When monitoring is resumed after a pause, an /ok ping is automatically sent to ensure you are not sent false alarms.

/pause/<hours>

"No alerts should be sent for __ hours"

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

Notes:
  • 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

Tip: If you prefer brevity you can use a 1 character abbreviated short form of each endpoint: /r, /c, /f and /p.

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 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:

  • 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.

Email Integration

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 {MONITOR_ID}@cronitor.link

To call different monitor events append the event name with a + as shown below.
d3x0c1+run@cronitor.link
d3x0c1+complete@cronitor.link
d3x0c1+fail@cronitor.link
d3x0c1+ok@cronitor.link

FAQs & Tips

Ping endpoints will accept GET, POST and HEAD 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