Heartbeats for scheduled AI jobs

Your AI job already runs from a native automation, deployment scheduler, queue, or worker. The missing piece is knowing when that independent clock stops producing successful work. This guide uses Crontap heartbeats as a dead-man switch: create a heartbeat, move its one-time secret ping URL into the job environment, report success or /fail, and inspect retained ping outcomes. Crontap monitors check-ins. It never starts, hosts, or wakes the job.

Before you start

• Identify the system that really starts the job and keep it in place.
• Measure normal runtime and scheduling jitter before choosing period and grace.
• Give the job a secret environment store that is not visible to model prompts or logs.
• Connect a supported client through the Crontap MCP hub.
• Verified against the Crontap heartbeat guide and public API documentation on 2026-09-15.

Choose where the job reports

Send success only after the useful work completes. If the agent writes a report and then uploads it, ping after the upload, not after the model call begins. On a known failure, send /fail after recording a concise non-secret message. If the process crashes before either path, silence eventually becomes the signal.

For a job expected every 60 minutes, periodMinutes: 60 means the next ping is expected 60 minutes after an accepted check-in. graceMinutes: 15 adds tolerance before the heartbeat becomes down. The first deadline starts only after the first accepted ping, so a newly created heartbeat remains pending until the job checks in.

Create one Crontap heartbeat named "hourly AI support digest" with periodMinutes 60 and graceMinutes 15. Before the write, explain when it becomes expected and when grace expires. After creation, do not reuse the returned ping URL in another prompt or message.

The MCP get_heartbeat and list_heartbeats reads omit the ping URL. Token rotation returns a new secret URL and immediately invalidates both the old success URL and its /fail variant. Rotation is destructive to the old credential, so it is not a casual way to retrieve a forgotten value.

Report success and explicit failure

Use a fixed environment variable, a short network timeout, and a finally or equivalent outcome path that does not hide the job's original exit status. The ping endpoint accepts GET, HEAD, or POST. A failure check-in appends /fail; success uses the base URL.

if run_support_digest; then
  curl --fail --silent --show-error \
    --max-time 10 "$CRONTAP_HEARTBEAT_URL"
else
  exit_code=$?
  curl --fail --silent --show-error \
    --max-time 10 "${CRONTAP_HEARTBEAT_URL%/}/fail" || true
  exit "$exit_code"
fi

List my heartbeats and retrieve "hourly AI support digest" by its exact ID. Report name, status, periodMinutes, graceMinutes, lastPingAt, expectedBy, and downAfter. Do not rotate the token, modify the heartbeat, or request its secret ping URL.

Inspect a UTC day of ping outcomes

get_heartbeat_pings requires the heartbeat ID and one UTC day such as 2026-09-15. Its safe output contains a day, aggregate event totals, and event outcome fields such as timestamps, kind, status, and failure markers when present. It does not return the ping URL or token.

For heartbeat ID HEARTBEAT_ID, get heartbeat pings for UTC day 2026-09-15. Summarize success, fail, missed, and recovery evidence using only returned fields. Do not expose or rotate the ping URL and do not change the heartbeat.

Verify the monitoring outcome

Check three systems. The native scheduler or queue should show that it started the job. The job logs should show the useful operation and its exit status without logging the heartbeat URL. Crontap should show an accepted ping and updated deadline. A successful ping proves the wrapper reached Crontap; your application output proves the AI job completed the intended work.

An explicit /fail moves a non-down heartbeat to down and records failed history. A later success recovers it. Silence first becomes late after the expected time, then down after period plus grace. Detection normally runs on a minute cadence, and alert delivery is asynchronous, so do not promise second-level notification timing.

Troubleshooting

The heartbeat stays pending

Creation does not start a deadline. Run the existing job through its real trigger and confirm the success path reaches the environment URL.

The heartbeat says up before work completes

Move the ping after the final durable output. A check-in at job start only proves the process began.

A failed job still sends success

Capture the original exit status before the curl command and route non-zero outcomes to /fail. Preserve the job's exit code.

The ping URL appeared in logs or chat

Rotate the heartbeat token, replace the encrypted environment value, and remove the exposed record where possible. The old URL becomes inert immediately.

A job is marked missed during normal variance

Measure the real interval and runtime jitter, then adjust grace through a reviewed update_heartbeat. Do not hide genuine missed executions with an excessive grace period.

Next steps

• Build the HTTP-clock alternative with Schedule API calls with an AI assistant.
• Investigate request outcomes with Debug a failed HTTP cron job with AI.
• Compare monitoring patterns in Dead-man switch explained.

Ready to monitor the existing job? Free forever tier. No credit card. Create your Crontap account →

Verified against current Crontap heartbeat and public API contracts on 2026-09-15. Sources: Crontap heartbeats and Crontap public API.