Progress Tracking

Pro Feature

Progress tracking is available on Pro and Business plans. The API accepts progress pings on all plans, but the dashboard UI requires a paid plan.

Overview

Jobs with multiple stages — ETL pipelines, data migrations, batch processing — can report their progress back to Cronping in real time. Instead of waiting for the grace period to expire when something stalls, you can see exactly which step is stuck.

Progress tracking builds on the existing /log endpoint by adding query parameters that carry structured progress metadata.

How It Works

Your job sends a /start ping when it begins
After each step, it sends a /log ping with progress query params
When done, it sends a success or fail ping

The dashboard shows a live progress bar and step timeline while the job is running.

Query Parameters

Add these to any /log ping URL:

Parameter	Type	Description
`progress`	`0-100`	Overall completion percentage
`step`	integer	Current step number (1-based)
`total`	integer	Total number of steps
`step_name`	string	Human-readable name of the current step

You can use any combination — all are optional. The request body is stored as the step's log message.

Examples

Simple percentage

curl -fsS "https://ping.cronping.com/<token>/log?progress=35"

Step-based with names

curl -fsS -X POST \
  "https://ping.cronping.com/<token>/log?step=3&total=8&step_name=transforming" \
  -d "Transformed 847,293 records"

Combined (percentage + steps + message)

curl -fsS -X POST \
  "https://ping.cronping.com/<token>/log?progress=66&step=4&total=6&step_name=loading" \
  -d "Loading into destination database..."

Full Script Example

#!/bin/bash
TOKEN="your-token-here"
BASE="https://ping.cronping.com/$TOKEN"

# Signal job start
curl -fsS "$BASE/start"

# Step 1: Extract
pg_dump "$SOURCE_DB" > /tmp/dump.sql
curl -fsS -X POST "$BASE/log?step=1&total=4&step_name=extraction&progress=25" \
  -d "Extracted $(wc -l < /tmp/dump.sql) rows"

# Step 2: Validate
validate_schema /tmp/dump.sql
curl -fsS -X POST "$BASE/log?step=2&total=4&step_name=validation&progress=50" \
  -d "Schema validated"

# Step 3: Transform
transform_data /tmp/dump.sql > /tmp/transformed.sql
curl -fsS -X POST "$BASE/log?step=3&total=4&step_name=transform&progress=75" \
  -d "Transformed $(wc -l < /tmp/transformed.sql) records"

# Step 4: Load
psql "$DEST_DB" < /tmp/transformed.sql
curl -fsS -X POST "$BASE/log?step=4&total=4&step_name=load&progress=100" \
  -d "Loaded into destination"

# Signal completion (exit code passthrough)
curl -fsS "$BASE/$?"

Python Example

import urllib.request
import urllib.parse

TOKEN = "your-token-here"
BASE = f"https://ping.cronping.com/{TOKEN}"

def report_progress(step: int, total: int, name: str, message: str = "", progress: int | None = None):
    params = urllib.parse.urlencode({
        "step": step,
        "total": total,
        "step_name": name,
        **({"progress": progress} if progress is not None else {}),
    })
    url = f"{BASE}/log?{params}"
    req = urllib.request.Request(url, data=message.encode() if message else None, method="POST")
    urllib.request.urlopen(req)

# Start
urllib.request.urlopen(f"{BASE}/start")

# Steps
extract_data()
report_progress(1, 3, "extraction", "500K rows extracted", progress=33)

transform_data()
report_progress(2, 3, "transform", "Data transformed", progress=66)

load_data()
report_progress(3, 3, "load", "Load complete", progress=100)

# Success
urllib.request.urlopen(BASE)

Dashboard View

When a heartbeat is running and progress pings have been received, the detail page shows:

Progress bar with current percentage
Step counter (e.g. "Step 3 of 6 — transform")
Step timeline showing completed, current, and pending steps
Latest message from the most recent progress ping

The progress card refreshes automatically every 10 seconds while the job is running.

How Progress Data Is Stored

Progress metadata is stored as structured JSON in the ping's body field:

{
  "message": "Transformed 847,293 records",
  "progress": 66,
  "step": 3,
  "stepTotal": 6,
  "stepName": "transform"
}

This means progress pings are also visible in the regular ping history table and can be used with Alert Rules if you check JSON fields.

Plan Limits

Plan	Progress Tracking	Step Timeline
Free	—	—
Basic	—	—
Pro	✅	✅
Business	✅	✅

The API always accepts progress query parameters regardless of plan. The dashboard progress UI is available on Pro and Business plans.

Tips

Use step + total for the best experience — this enables the step timeline view in the dashboard.
Always send /start before progress pings — the dashboard only shows progress for the current run (after the most recent /start).
Use step_name for readability — names like "extraction", "transform", "load" are much clearer than step numbers alone.
Include a message in the body — the body text is shown as a log entry alongside the progress.
Keep step names short — they're displayed in a compact timeline view.

Ping API Reference — full endpoint documentation
Attaching Logs — send job output with pings
Monitoring Cron Jobs — getting started guide

Progress Tracking

On this page