Telemetry API

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

Jobs use telemetry events to track the start time, end time, and outcome of a cron job, scheduled task, or other 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:

https://cronitor.link/p/:apiKey/:monitorKey

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

You can also copy the complete telemetry URL from your monitor. It contains a telemetry-only key, which can only send events, so it is not a secret.

Basic Usage: Jobs

# Send a run event to indicate a job has started.
curl --fail "https://cronitor.link/p/:apiKey/nightly-job?state=run"
# Send a complete event to indicate a job has completed successfully.
curl --fail "https://cronitor.link/p/:apiKey/nightly-job?state=complete"
# Send a failure event to report an error.
curl --fail "https://cronitor.link/p/:apiKey/nightly-job?state=fail"

Replace :apiKey with your API key and nightly-job with your monitor key.

Basic Usage: Heartbeats

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

A request to a /p/ URL without a state parameter records a tick event. It records activity without starting a job run that needs a corresponding completion event.

Event Parameters

Telemetry events can be enriched by sending optional query parameters along with each request.

Parameter	Description
`env`	The environment the telemetry event is being sent from. Use this for monitors running in multiple environments, such as 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 2,000 characters.
`metric`	A built-in or custom metric in `name:value` form. `name=value` is also accepted. Repeat the parameter to send multiple metrics. See Metrics.
`series`	A unique user-supplied ID to match related `run` and `complete` or `fail` events. It improves matching accuracy when jobs ping every few seconds.
`state`	`run`: a job has started. `complete`: a job completed successfully. `fail`: a job failed or an error occurred. `tick`: record activity without starting a run. `ok`: manually reset the monitor to a passing state. Omitting `state` on a `/p/` URL records a `tick`.
`status_code`	Exit code returned from a job.

Parameter Usage Examples

Use --get and --data-urlencode to construct requests containing spaces or special characters:

# Send a run event from a specific host with a message.
curl --fail --get "https://cronitor.link/p/:apiKey/nightly-job" \
  --data-urlencode "state=run" \
  --data-urlencode "host=worker-01" \
  --data-urlencode "message=Job started by August"

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

# Send a failure event with an error message.
ERROR_MESSAGE="Source database did not respond"
curl --fail --get "https://cronitor.link/p/:apiKey/nightly-job" \
  --data-urlencode "state=fail" \
  --data-urlencode "message=$ERROR_MESSAGE"

Metrics

Metrics can be attached to both heartbeat and job lifecycle events. Built-in metrics include count (items processed or other important events), error_count (errors encountered), and duration (execution time in seconds).

You can also send custom metrics such as queue_depth or quality_score. Repeat metric once per value:

curl --fail --get "https://cronitor.link/p/:apiKey/queue-worker" \
  --data-urlencode "metric=count:100" \
  --data-urlencode "metric=error_count:5" \
  --data-urlencode "metric=queue_depth:142" \
  --data-urlencode "metric=quality_score:0.87"

Do not combine multiple metrics into one comma-separated value. See Custom Metrics for naming rules, limits, charts, and alert assertions, including how missing values and zeros are handled.

Anonymous Events

Cronitor auto-assigns a short, unique code to every monitor. This allows anonymous telemetry events that do not include an API key for authentication.

Anonymous telemetry events were the original integration mechanism for Cronitor and remain supported. Accounts created after January 11, 2021 must enable anonymous events on the API settings page.

# Send an event using the monitor's short code.
curl --fail "https://cronitor.link/d3x0c1"
# Send a run event to indicate a job has started.
curl --fail "https://cronitor.link/d3x0c1/run"
# Send a complete event to indicate a job has completed successfully.
curl --fail "https://cronitor.link/d3x0c1/complete"
# Send a failure event to report an error.
curl --fail "https://cronitor.link/d3x0c1/fail"

Replace d3x0c1 with your monitor's short code. A bare code-only URL defaults to a run event; a bare /p/:apiKey/:monitorKey URL defaults to a tick.

Email Integration

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

Send heartbeat emails to:

{your-monitor-code}@cronitor.link

To report lifecycle events, append the state with a +:

# Indicate a job has started.
d3x0c1+run@cronitor.link
# Indicate a job has completed successfully.
d3x0c1+complete@cronitor.link
# Report a failure.
d3x0c1+fail@cronitor.link

Rate Limiting

Cronitor limits requests to prevent accidental flooding of the Telemetry Events API. Requests over the limit receive an HTTP 429 status code.

Each monitor endpoint allows 10 requests per second, with bursts up to 400 pings beyond the limit.
Each IP address allows 50 requests per second, with bursts up to 800 pings beyond the limit.

FAQs & Tips

A successful response means Cronitor received the request. It does not prove that the event was stored or matched a monitor. To verify, check the monitor after one real run: get_status({"key": "nightly-job"}) with the MCP server, cronitor status nightly-job with CronitorCLI, or the monitor's page in the dashboard.
In production, add a timeout and retries so a slow network neither hangs the job nor drops the event: curl -fsS -m 10 --retry 3 "https://cronitor.link/p/:apiKey/nightly-job?state=complete".
Telemetry URLs accept GET, POST, and HEAD requests. POST bodies are discarded; send event data as query parameters.
Telemetry URLs were originally hosted on cronitor.io. Cronitor launched cronitor.link in February 2015 to isolate and optimize bursty telemetry traffic.
Unencrypted HTTP pings are accepted only on cronitor.link. Requests sent over HTTP to cronitor.io are redirected to HTTPS.

Regional endpoints

Cronitor also accepts telemetry on eu.cronitor.link, served from Germany. cronitor.link is the right default for most workloads; for latency-sensitive workloads, use whichever host is closer. Both accept the same URLs, API keys, and monitors:

https://eu.cronitor.link/p/:apiKey/:monitorKey

It changes only where requests are received. Events are processed and stored in the same place as events sent to cronitor.link, so it is not a data residency option.