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}/start

Basic Example

#!/bin/bash

# Signal job start
curl -X POST -u YOUR_API_KEY: https://cron.life/ping/backup-job/start

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

# Signal completion (see below)
curl -X POST -u YOUR_API_KEY: https://cron.life/ping/backup-job/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}/complete

Basic Example

curl -X POST -u YOUR_API_KEY: https://cron.life/ping/backup-job/complete

Response (200 OK)

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

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

Fail Job

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

Endpoint

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

Parameters

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

Examples

# Without error message
curl -X POST -u YOUR_API_KEY: \
  https://cron.life/ping/backup-job/fail

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

# With detailed error
curl -X POST -u YOUR_API_KEY: \
  'https://cron.life/ping/backup-job/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"
}

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

Complete Lifecycle Pattern

Here's how to use all three endpoints together for full job tracking:

#!/bin/bash
set -e  # Exit on error

API_KEY="YOUR_API_KEY"
MONITOR="backup-job"
BASE_URL="https://cron.life/ping"

# Signal start
curl -X POST -u "$API_KEY:" "$BASE_URL/$MONITOR/start"

# Run job with error handling
if /path/to/backup.sh; then
    # Success - signal completion
    curl -X POST -u "$API_KEY:" "$BASE_URL/$MONITOR/complete"
else
    # Failure - signal with exit code
    curl -X POST -u "$API_KEY:" "$BASE_URL/$MONITOR/fail?message=Exit%20code%20$?"
    exit 1
fi

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