Telemetry API

Sending telemetry events is the core integration mechanism for Cronitor's Job and Heartbeat monitors.

Jobs use telemetry events to implement a state machine that tracks the start time, end time and exit state of a cron job/scheduled task or other long running background process.

Heartbeats use telemetry events to record periodic system health, output and metrics.

Sending Events

The Telemetry Events API is hosted on a separate domain - cronitor.link. Events are sent by making http requests to the following URL:

# Base Telemetry URL
https://cronitor.link/p/:apiKey/:monitorKey

Param	Description
`:apiKey`	Requests are authenticated by including an API key in the URL. Key must have permisson `monitor:telemetry`.
`:monitorKey`	A unique identifier for your monitor. If no monitor matches the provided key, a new monitor will be created automatically.

Basic Usage: Jobs

# send a run event to indicate a job has started
curl https://cronitor.link/p/:apiKey/nightly-job?state=run
# send a complete event to indicate a job has completed successfully
curl https://cronitor.link/p/:apiKey/nightly-job?state=complete
# send a failure event to trigger an immediate alert
curl https://cronitor.link/p/:apiKey/nightly-job?state=fail

Basic Usage: Heartbeats

# send a heartbeat event
curl https://cronitor.link/p/:apiKey/airflow-heartbeat
# send a heartbeat event with count and error count
curl https://cronitor.link/p/:apiKey/address-verification-counts?metric=count:100&metric=error_count:5

Event Parameters

Telemetry events can be enriched by sending optional query parameters along with each request. In the Basic Usage examples above, the state, count and error_count params were all used.

Parameter	Description
`env`	The environment the telemetry event is being sent from. Use this for monitors that are running in multiple environments (e.g. staging and production). Alerting can be configured per environment.
`host`	The hostname of the server sending the telemetry event.
`message`	A url-encoded message of up to 2000 characters.
`metric`	Performance related metrics. Options: `count:`: record counts of important events. `duration:`: the duration of the job/task being monitored. `error_count:*`: the number of errors that occurred.
`series`	A unique user-supplied ID to collate related pings, i.e. matching `state=run` and `state=complete
`state`	Indicate a state change for a monitor. Must be one of: `run` - a job has started running. `complete` - a job completed successfully. `fail` - a job failed/an error occurred. `ok` - manually reset the monitor to a passing state.
`status_code`	Exit code returned from a job.

Parameters Usage Examples

# send an event to indicate that a job has been started on a specific host, by a specific user
curl https://cronitor.link/p/:apiKey/nightly-job?state=run&host=10.0.01&message='Job started by August'

# send a pair of run and complete events with the same series
curl https://cronitor.link/p/:apiKey/nightly-job?state=run&series=abcd
curl https://cronitor.link/p/:apiKey/nightly-job?state=complete&series=abcd

# send a failure event with an error message
curl https://cronitor.link/p/:apiKey/nightly-job?state=fail&message=$ERROR_MESSAGE

# send a complete event with count and error count
curl https://cronitor.link/p/:apiKey/address-verification-counts?state=complete&metric=count:100&metric=error_count:5

Anonymous Events

Cronitor auto-assigns a short, unique ID for every monitor that is created (called "key" on the dashboard and API). This allows anonymous telemetry events — events that don't use an API Key for authentication.

Anonymous telemetry events were the original integration mechanism for Cronitor, and will always be supported.

Accounts created after January 11th, 2021 require anonymous events to be enabled from the API settings page.

# Send a heartbeat event
curl https://cronitor.link/d3x0c1
# send a run event to indicate a job has started
curl https://cronitor.link/d3x0c1/run
# send a complete event to indicate a job has completed successfully
curl https://cronitor.link/d3x0c1/complete
# send a failure event to trigger an immediate alert
curl https://cronitor.link/d3x0c1/fail

Tip: While Cronitor's globally assigned ID's may look like a plain hash, each contains an embedded checksum, which gives us the ability to filter/block malicious traffic.

Email Integration

The Telemetry Events API supports sending events via email (SMTP) in addition HTTP. To send telemetry events via email you must first enable anonymous events.

Heartbeat events are tracked by sending an email to

{your-monitor-key}@cronitor.link

To report lifecycle events append the state with a + as shown below.

# send a run event to indicate a job has started
d3x0c1+run@cronitor.link
# send a complete event to indicate a job has completed successfully
d3x0c1+complete@cronitor.link
# send a failure event to trigger an immediate alert
d3x0c1+fail@cronitor.link

Rate Limiting

In order to prevent users from accidentally flooding the Telemetry Events API (and potentially disrupting service for other users), Cronitor imposes rate limits on the number of requests that can be made to the Telemetry Events 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

Telemetry URLs will accept GET, POST and HEAD requests. At this time, all POST bodies are discarded.
Telemetry URLs were originally 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 bursts of traffic (think midnight UTC).
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.