Lifecycle Tracking API

Track the complete lifecycle of your cron jobs with start, complete, and fail endpoints. Measure execution duration, detect hung jobs, and receive immediate alerts on failures.

Why Lifecycle Tracking?

Instead of just pinging when a job completes, lifecycle tracking gives you visibility into:

Execution Duration: How long does each job take?
Hung Jobs: Detect jobs that start but never complete
Immediate Failure Alerts: No grace period on explicit failures
Error Messages: Capture and display failure reasons

Start Job

Record when a job begins execution. Useful for detecting jobs that start but never complete.

Endpoint

POST /ping/{monitor_key}/{api_key}/start

#!/bin/bash

# Signal job start
curl https://cron.life/ping/backup-job/ck_app_demo_key/start

# Run your job
/path/to/backup.sh

# Signal completion (see below)
curl https://cron.life/ping/backup-job/ck_app_demo_key/complete

Response · 200 OK

{
  "status": "started",
  "monitor": "backup-job",
  "startedAt": "2025-01-15T02:00:00Z"
}

Complete Job

Record successful job completion. Calculates execution duration if preceded by a start ping.

Endpoint

POST /ping/{monitor_key}/{api_key}/complete

Duration is returned in seconds. In the example response, the job took 15 minutes and 30 seconds (930 seconds).

curl https://cron.life/ping/backup-job/ck_app_demo_key/complete

Response · 200 OK

{
  "status": "completed",
  "monitor": "backup-job",
  "completedAt": "2025-01-15T02:15:30Z",
  "duration": 930
}

Fail Job

Record job failure with optional error message. Triggers immediate alert (no grace period).

Endpoint

POST /ping/{monitor_key}/{api_key}/fail?message={error_message}

Parameters

Parameter	Type	Description
`message`	string	Optional error message shown in alerts and dashboard

Immediate Alerts: Failure pings trigger alerts immediately without waiting for the grace period. You're notified the moment a job fails, not when it misses its next scheduled run.

# Without error message
curl https://cron.life/ping/backup-job/ck_app_demo_key/fail

# With error message
curl 'https://cron.life/ping/backup-job/ck_app_demo_key/fail?message=Database%20connection%20timeout'

# With detailed error
curl 'https://cron.life/ping/backup-job/ck_app_demo_key/fail?message=Failed%20at%20step%203:%20disk%20full'

Response · 200 OK

{
  "status": "failed",
  "monitor": "backup-job",
  "failedAt": "2025-01-15T02:10:00Z",
  "message": "Database connection timeout"
}

Benefits Over Simple Ping

Feature	Simple Ping	Lifecycle
Execution Duration	Not tracked	Calculated automatically
Hung Job Detection	No visibility	Detect started but not completed
Failure Alerts	Wait for grace period	Immediate on /fail
Error Messages	Not captured	Shown in dashboard & alerts

When to Use Lifecycle Tracking

Use Lifecycle When:

Jobs have complex error handling
Execution duration matters (performance monitoring)
Jobs can hang or run indefinitely
You need immediate failure notifications
Debugging requires error context

Use Simple Ping When:

Jobs are simple and rarely fail
You only care about "did it run?"
Minimal integration effort is priority
One-line monitoring is sufficient

Error Responses

Lifecycle endpoints fail the same way as ping. A failed lifecycle call never throws inside your job — the SDKs swallow it and log to stderr — but when calling the HTTP API directly, handle these:

404 Monitor Not Found

Returned when you call /start, /complete, or /fail on a monitor that was never registered.

{
  "error": "MONITOR_NOT_FOUND",
  "message": "Monitor 'backup-job' not found. Provide schedule parameter for auto-registration."
}

Fix: Send one ping with ?schedule= first (see self-healing ping) or register via bulk sync, then resume lifecycle calls.

401 Unauthorized

Returned when API key authentication fails.

{
  "error": "AUTHENTICATION_REQUIRED",
  "message": "API key authentication is required"
}

Fix: Confirm the /ping/{monitor_key}/{api_key}/... path includes a valid key. See Authentication.

429 Rate Limit Exceeded

Returned when the API rate limit (1000 requests per minute) is exceeded.

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "API rate limit exceeded",
  "retry_after": 45
}

Fix: Back off for retry_after seconds. Lifecycle calls are once per run, so this only happens with very high job frequency.