Ping API

Record cron job executions with simple HTTP pings. Monitors auto-register when you include schedule parameters, enabling self-healing monitoring without manual setup.

Basic Ping

The simplest way to monitor a job: send an HTTP ping when it executes successfully.

Endpoint

GET /ping/{monitor_key}
POST /ping/{monitor_key}

Both GET and POST are supported. Use whichever is more convenient for your setup.

cURL Examples

# GET request (simplest)
curl -u ck_app_12345_abcdef: https://cron.life/ping/daily-backup

# POST request
curl -X POST -u ck_app_12345_abcdef: https://cron.life/ping/daily-backup

In Your Crontab

# Run script, then ping on success
0 2 * * * /path/to/backup.sh && curl -u YOUR_API_KEY: https://cron.life/ping/backup

Response (200 OK)

{
  "status": "ok",
  "monitor": "daily-backup",
  "pingedAt": "2025-01-15T02:00:00Z"
}

Self-Healing Ping (Auto-Register)

Include schedule and grace period parameters to auto-create monitors on first ping. If the monitor doesn't exist, it's created automatically. If it was deleted, it's recreated.

Endpoint

GET /ping/{monitor_key}?schedule={cron_expression}&gracePeriod={seconds}

Parameters

ParameterTypeDescription
schedulestringCron expression (URL-encoded). Example: 0%202%20*%20*%20*
gracePeriodintegerGrace period in seconds. Default: 60. Prevents false alerts from minor delays.
namestringOptional human-readable name. Default: generated from monitor_key

Examples

# Daily at 2 AM with 5-minute grace period
curl -u YOUR_API_KEY: \
  'https://cron.life/ping/daily-backup?schedule=0%202%20*%20*%20*&gracePeriod=300'

# Every 15 minutes with default 60s grace period
curl -u YOUR_API_KEY: \
  'https://cron.life/ping/sync-data?schedule=*/15%20*%20*%20*%20*'

# Hourly with custom name
curl -u YOUR_API_KEY: \
  'https://cron.life/ping/report-gen?schedule=0%20*%20*%20*%20*&name=Generate%20Reports'

How Self-Healing Works:

  1. First ping with schedule parameter → Monitor created automatically
  2. Subsequent pings → Schedule parameter no longer required
  3. If monitor deleted → Next ping with schedule recreates it

URL Encoding Reference

Cron expressions must be URL-encoded. Spaces become %20:

Cron ExpressionURL-Encoded
0 2 * * *0%202%20*%20*%20*
*/15 * * * **/15%20*%20*%20*%20*
0 */6 * * *0%20*/6%20*%20*%20*

Monitor Keys

Monitor keys identify your jobs and appear in URLs. Choose clear, descriptive keys.

Key Guidelines

  • Use lowercase: daily-backup not Daily-Backup
  • Use hyphens or underscores: send-emails or send_emails
  • Be descriptive: backup-prod-db not job1
  • Alphanumeric only: Letters, numbers, hyphens, underscores

Good Examples

backup-production-database
process-payment-queue
send-weekly-reports
sync-user-data
cleanup-temp-files

Avoid

job1
cronjob
test
my job (spaces)
Backup-Job (uppercase)

Supported Cron Formats

CronRadar supports multiple cron expression formats:

Standard Cron (5 fields)

# ┌───────────── minute (0 - 59)
# │ ┌───────────── hour (0 - 23)
# │ │ ┌───────────── day of month (1 - 31)
# │ │ │ ┌───────────── month (1 - 12)
# │ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
# │ │ │ │ │
# * * * * *

0 2 * * *          # Daily at 2:00 AM
0 */6 * * *        # Every 6 hours
*/15 * * * *       # Every 15 minutes
0 0 1 * *          # First day of every month
0 0 * * 0          # Every Sunday at midnight

Extended Cron (6 fields, with seconds)

# ┌────── second (0 - 59)
# │ ┌────── minute (0 - 59)
# │ │ ┌───── hour (0 - 23)
# │ │ │ ┌──── day of month (1 - 31)
# │ │ │ │ ┌─── month (1 - 12)
# │ │ │ │ │ ┌── day of week (0 - 6)
# │ │ │ │ │ │
# * * * * * *

0 0 2 * * *        # Daily at 2:00:00 AM
*/30 * * * * *     # Every 30 seconds

Special Strings

@hourly           # 0 * * * *
@daily            # 0 0 * * *
@weekly           # 0 0 * * 0
@monthly          # 0 0 1 * *
@yearly           # 0 0 1 1 *

Error Responses

404 Monitor Not Found

Returned when monitor doesn't exist and no schedule parameter provided.

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

Fix: Add ?schedule=... to your ping URL.

400 Invalid Schedule

Returned when the cron expression is malformed or invalid.

{
  "error": "INVALID_SCHEDULE",
  "message": "Invalid cron expression: '0 25 * * *' (hour must be 0-23)"
}

401 Unauthorized

Returned when API key authentication fails.

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

Fix: Check your API key and ensure you're using proper authentication. See Authentication docs.

Next Steps

Was this page helpful?