API Docs

Ping API

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.

Cronitor provides both an installabled CLI, as well as language-specific SDKs, to make it easy to use this API from within your system.

To understand this API we must look at two key aspects, the Resources that is exposes and the Telemetry Events that it supports.

Resources

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.

Resource Description
Monitor cronitor.link/:monitorId/:event
Organization cronitor.link/ping/:pingAPIKey/:uniqueId/:event

Unique Identifiers

  • Cronitor assigns a globally unique identifier to every monitor. These :monitorIds can be used to send telemetry events to the Monitor resource, e.g. cronitor.link/d3x0c1/:event

  • You can provide your own unique identifier for a monitor when pinging the Organization resource, e.g.

    cronitor.link/ping/a9ff42ad0abc1/generate-invoices/:event

    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.

Telemetry Event Endpoints

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.

  • Jobs  monitor the execution of a backend job (cron job, windows scheduled task, systemd timer, etc). This involves tracking the lifecycle of the job - that is, the start time, end time and exit state of the job.
  • Events  monitor the health of a system via periodic heartbeat events. There is no lifecycle to measure, only the occurrence (or absence) of healthy/unhealthy events.
Endpoint Description Used For
/run Report job is running Jobs
/complete Report job is complete Jobs
/tick Report an event occurred private beta Events
/fail Report a failure/error Jobs   Events
/ok Manually reset a monitor to a healthy state Jobs   Events
/pause/<hours> Pause alerting for given <hours> Jobs   Events

/run

"Job Is Running"

Ping the /run endpoint to report that your job 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 job into a running state on your dashboard.

/complete

"Job Completed Successfully"

Ping the /complete endpoint to report that your job has completed successfully.

/tick

"Event Has Occurred"

Ping the /tick endpoint to report that an event you wish to monitor occurred.

/fail

"Job Has Failed" or "Error Has Occurred"

Ping the /fail endpoint to report that your job has failed. When a failure is reported you will be alerted immediately.

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 job is running and failing rapidly, alerts are batched to one per minute.

/ok

"Monitor 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 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/200000
  • 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
message run, complete, fail A url-encoded message, up to 2000 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 Ping API authentication 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, 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:

  • 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 Cronitor's globally assigned ID's might look like it a plain hash, each contains an embedded checksum. This gives us the ability to detect and filter unwanted traffic.

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

Rate Limiting

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.

  • Each event endpoint (run, complete, fail, etc) allows 5 requests/sec with bursts up to 10 pings beyond the limit.
  • Each IP address is allowed 50 requests/sec, with bursts of 250 pings beyond the limit.

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