API Documentation

Everything you need to monitor your cron jobs, scheduled tasks, and background workers with CronPeek.

Quick Start

Get from zero to monitoring in under 60 seconds. Three API calls is all it takes.

Create an account

curl -X POST "https://cronpeek.web.app/api/v1/accounts" \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Create a monitor

Tell CronPeek what to watch. Set the expected interval in seconds between pings.

curl -X POST "https://cronpeek.web.app/api/v1/monitors" \
  -H "x-api-key: cpk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Nightly DB Backup", "schedule": 86400}'

Ping from your cron job

Add a single line to the end of your script. If the ping stops arriving, CronPeek alerts you.

# Add to the end of your cron script
curl -s "https://cronpeek.web.app/api/v1/ping/YOUR_PING_TOKEN"

📦

Postman Collection — Download JSON and import into Postman to try every endpoint instantly.

Base URL

https://cronpeek.web.app

All API endpoints are under /api/v1/. All requests and responses use JSON (except ping endpoints which also accept GET/HEAD with no body).

Authentication

Most endpoints require your API key in the x-api-key header. You get a key when you create an account.

curl -H "x-api-key: cpk_your_key_here" "https://cronpeek.web.app/api/v1/monitors"

Key format: API keys start with cpk_ followed by a 32-character hex string.

No auth required: Account creation and ping endpoints do not require the x-api-key header. Ping endpoints authenticate via their unique token in the URL.

Create Account

POST /api/v1/accounts No auth

Create a free account and receive your API key. If an account already exists for the email, the existing key is returned.

Request body

Field	Type	Required	Description
email	string	Yes	Valid email address

Example

curl -X POST "https://cronpeek.web.app/api/v1/accounts" \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@company.com"}'

Response 201

{
  "apiKey": "cpk_a1b2c3d4e5f6...",
  "plan": "free",
  "monitors": 5
}

Create Monitor

POST /api/v1/monitors API key required

Create a new monitor. You'll receive a unique ping URL that your cron job should hit on each successful run.

Request body

Field	Type	Required	Description
name	string	Yes	Human-readable name for this monitor
schedule	integer	Yes	Expected seconds between pings (min: 60)
grace	integer	No	Grace period in seconds before alerting. Defaults to 10% of schedule (min: 60s)
alertEmail	string	No	Override alert email (defaults to account email)
alertWebhook	string	No	Webhook URL to POST when monitor goes down

Common schedule values

Interval	Seconds
Every minute	`60`
Every 5 minutes	`300`
Every hour	`3600`
Every day	`86400`
Every week	`604800`

Example

curl -X POST "https://cronpeek.web.app/api/v1/monitors" \
  -H "x-api-key: cpk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly DB Backup",
    "schedule": 86400,
    "grace": 3600,
    "alertWebhook": "https://hooks.slack.com/services/T00/B00/xxx"
  }'

Response 201

{
  "monitorId": "a1b2c3d4e5f67890",
  "name": "Nightly DB Backup",
  "pingUrl": "https://cronpeek.web.app/api/v1/ping/abc123def456...",
  "schedule": 86400,
  "grace": 3600,
  "status": "new"
}

Save the pingUrl -- this is the URL your cron job will call to report success.

List Monitors

GET /api/v1/monitors API key required

List all monitors for your account, ordered by creation date (newest first).

Example

curl -H "x-api-key: cpk_your_key_here" \
  "https://cronpeek.web.app/api/v1/monitors"

Response 200

{
  "monitors": [
    {
      "monitorId": "a1b2c3d4e5f67890",
      "name": "Nightly DB Backup",
      "status": "up",
      "schedule": 86400,
      "grace": 3600,
      "lastPing": "2026-03-28T02:00:12.000Z",
      "pingCount": 47
    }
  ],
  "count": 1
}

Monitor statuses

Status	Meaning
new	Monitor created, waiting for the first ping
up	Pings arriving on schedule
down	Ping missed -- schedule + grace period exceeded
paused	Monitoring paused (no alerts)

Monitor Status

GET /api/v1/monitors/:id/status API key required

Get detailed status for a single monitor, including last ping and last alert timestamps.

Example

curl -H "x-api-key: cpk_your_key_here" \
  "https://cronpeek.web.app/api/v1/monitors/a1b2c3d4e5f67890/status"

Response 200

{
  "monitorId": "a1b2c3d4e5f67890",
  "name": "Nightly DB Backup",
  "status": "up",
  "schedule": 86400,
  "grace": 3600,
  "lastPing": "2026-03-28T02:00:12.000Z",
  "lastAlert": null,
  "pingCount": 47
}

Delete Monitor

DELETE /api/v1/monitors/:id API key required

Permanently delete a monitor. This frees up one slot in your monitor limit.

Example

curl -X DELETE \
  -H "x-api-key: cpk_your_key_here" \
  "https://cronpeek.web.app/api/v1/monitors/a1b2c3d4e5f67890"

Response 200

{
  "deleted": true
}

Send Ping

GET POST HEAD /api/v1/ping/:token No auth

Report a successful job run. Accepts GET, POST, or HEAD requests. The token is provided in the pingUrl when you create a monitor. No API key needed -- the token itself authenticates the ping.

Example

# GET (simplest -- works from a browser or curl one-liner)
curl "https://cronpeek.web.app/api/v1/ping/abc123def456..."

# HEAD (minimal -- no response body, lowest bandwidth)
curl -I "https://cronpeek.web.app/api/v1/ping/abc123def456..."

# POST (useful if your HTTP client defaults to POST)
curl -X POST "https://cronpeek.web.app/api/v1/ping/abc123def456..."

Response 200 (GET/POST)

{
  "ok": true,
  "monitor": "Nightly DB Backup",
  "status": "up"
}

HEAD requests return 200 with no body.

Health Check

GET /api/health No auth

Check if the CronPeek API is online. Useful for your own monitoring or status pages.

curl "https://cronpeek.web.app/api/health"

Response 200

{
  "status": "ok",
  "service": "cronpeek",
  "version": "1.0.0",
  "timestamp": "2026-03-28T12:00:00.000Z"
}

Integration Examples

Add CronPeek to any scheduled task that can make an HTTP request. Below are copy-paste examples for common setups.

Linux crontab

# Run backup every night at 2 AM, ping CronPeek on success
0 2 * * * /usr/local/bin/backup.sh && curl -s "https://cronpeek.web.app/api/v1/ping/YOUR_TOKEN"

Ping from code

#!/bin/bash
# Your job logic here
/usr/local/bin/process-data.sh

# Ping CronPeek on success (fire-and-forget)
curl -fsS --retry 3 --max-time 10 \
  "https://cronpeek.web.app/api/v1/ping/YOUR_TOKEN"

const https = require('https');

async function pingCronPeek(token) {
  return new Promise((resolve) => {
    https.get(
      `https://cronpeek.web.app/api/v1/ping/${token}`,
      (res) => resolve(res.statusCode)
    ).on('error', () => resolve(null));
  });
}

// Usage: call after your job completes
await pingCronPeek('YOUR_TOKEN');

import requests

def ping_cronpeek(token):
    try:
        requests.get(
            f"https://cronpeek.web.app/api/v1/ping/{token}",
            timeout=10
        )
    except requests.RequestException:
        pass  # Don't let monitoring failures break your job

# Usage: call after your job completes
ping_cronpeek("YOUR_TOKEN")

AWS Lambda (scheduled via EventBridge)

const https = require('https');

exports.handler = async (event) => {
  // --- Your Lambda logic ---
  const result = await doWork();

  // --- Ping CronPeek on success ---
  await new Promise((resolve) => {
    https.get(
      "https://cronpeek.web.app/api/v1/ping/YOUR_TOKEN",
      resolve
    ).on('error', resolve);
  });

  return { statusCode: 200, body: "done" };
};

Python cron script / Celery beat

import subprocess
import requests

def run_etl_pipeline():
    # Your ETL / data processing logic
    subprocess.run(["python", "etl.py"], check=True)

    # Ping CronPeek on success
    requests.get(
        "https://cronpeek.web.app/api/v1/ping/YOUR_TOKEN",
        timeout=10
    )

if __name__ == "__main__":
    run_etl_pipeline()

GitHub Actions (scheduled workflow)

# .github/workflows/nightly.yml
name: Nightly Job
on:
  schedule:
    - cron: '0 2 * * *'

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: ./scripts/process.sh
      - name: Ping CronPeek
        run: curl -fsS "https://cronpeek.web.app/api/v1/ping/${{ secrets.CRONPEEK_TOKEN }}"

Kubernetes CronJob

apiVersion: batch/v1
kind: CronJob
metadata:
  name: nightly-backup
spec:
  schedule: "0 2 * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: backup
            image: myapp:latest
            command:
            - /bin/sh
            - -c
            - "/app/backup.sh && curl -s https://cronpeek.web.app/api/v1/ping/$CRONPEEK_TOKEN"
            env:
            - name: CRONPEEK_TOKEN
              valueFrom:
                secretKeyRef:
                  name: cronpeek
                  key: token
          restartPolicy: OnFailure

Pricing

Simple, flat pricing. No per-monitor fees. No surprises.

Free

$0/mo

For side projects

5 monitors
7-day history
Email alerts
1-minute minimum interval

Starter

$9/mo

For growing teams

50 monitors
90-day history
Email + webhook alerts
1-minute minimum interval
Slack integration

Pro

$29/mo

For production infra

Unlimited monitors
Unlimited history
Email + webhook alerts
1-minute minimum interval
Slack + PagerDuty
Priority support

Error Codes

200Success

201Resource created (account, monitor)

400Bad request -- missing or invalid fields

401Unauthorized -- missing or invalid API key

403Forbidden -- monitor limit reached, or accessing another account's resource

404Not found -- invalid monitor ID or ping token

500Server error -- try again or contact support

Error responses return JSON with an error field:

{
  "error": "Monitor limit reached (5). Upgrade your plan for more monitors."
}

API Documentation

On this page

Quick Start

Create an account

Create a monitor

Ping from your cron job

Base URL

Authentication

Create Account

Request body

Example

Response 201

Create Monitor

Request body

Common schedule values

Example

Response 201

List Monitors

Example

Response 200

Monitor statuses

Monitor Status

Example

Response 200

Delete Monitor

Example

Response 200

Send Ping

Example

Response 200 (GET/POST)

Health Check

Response 200

Integration Examples

Linux crontab

Ping from code

AWS Lambda (scheduled via EventBridge)

Python cron script / Celery beat

GitHub Actions (scheduled workflow)

Kubernetes CronJob

Pricing

Error Codes