How to Add a Cron Monitoring Badge to Your GitHub README

Status badges are a staple of well-maintained open source projects. Build status, test coverage, npm version — they give visitors an instant signal that the project is healthy and actively maintained. But one category of status has been missing from most READMEs: cron job health.

If your project includes scheduled tasks — data imports, feed generation, cache rebuilds, certificate renewals — a live cron monitoring badge tells contributors and users that those background processes are actually running. This guide shows you how to set one up with Crontiq in under five minutes.

Why Cron Status Badges Matter

For open source projects that rely on scheduled jobs, the badge answers a question that documentation cannot: is it running right now? A README can describe the cron setup, but only a live badge proves it is working.

Common use cases for cron status badges:

• Data pipelines — Show that the nightly data refresh completed successfully
• Feed generators — Prove that RSS/Atom feeds are being updated on schedule
• Backup scripts — Display the last successful backup time
• Scrapers and crawlers — Confirm that data collection is running
• Certificate renewals — Show that TLS certificates are being renewed automatically

The badge also serves as a transparency signal. Users can click through to a public status page with sparkline charts showing recent ping history, without needing any login or access to your infrastructure.

Step-by-Step Setup

Step 1: Create a Crontiq Account

Register at crontiq.io/register with your email address. You will receive an API key (starting with cq_live_) and can manage your monitors from the dashboard.

Step 2: Set Up the Monitor

Add a curl call to your cron job. The monitor is auto-provisioned on the first ping — no dashboard configuration needed:

After the first ping, Crontiq creates the monitor data-sync and assigns it a public token (starting with cq_chk_). You can find this token in the dashboard under the monitor settings.

Step 3: Get the Badge URL

Every monitor has an SVG badge endpoint. The URL format is:

The badge dynamically reflects the current monitor status:

• UP (green #00FF88) — Last ping received on time
• DOWN (red #FF4D4D) — Pings have stopped or job reported failure
• WARNING (purple #7C5CFC) — Anomaly detected in JSON metrics
• LATE (amber #F0A500) — Ping overdue but within grace period
• NEW (gray #8B949E) — Monitor just created, awaiting first ping

Step 4: Add the Badge to Your README

Use standard Markdown image syntax. Link the badge to your public status page so visitors can click through for details:

For HTML-based READMEs or documentation sites:

Place the badge near the top of your README, alongside other status badges like CI/CD and test coverage.

Customizing the Badge

Custom Labels

By default, the badge displays "crontiq" on the left side and the status on the right. You can customize the label with the label query parameter:

Showing Metrics on the Badge

If your cron job sends JSON metrics, you can display a specific metric value on the badge instead of the status text:

This turns the badge into a live data display. For data-oriented projects, showing the latest row count or processing time is more informative than a simple "up" status.

Multiple Badges

If your project has multiple cron jobs, add a badge for each one. This gives visitors a complete picture of your background infrastructure:

Caching and Freshness

Crontiq serves badge SVGs with a Cache-Control header that allows CDNs and browsers to cache the image for 60 seconds. This means the badge may take up to one minute to reflect a status change. For most cron jobs that run hourly or daily, this is more than sufficient.

GitHub's own CDN (camo) also caches images. If you need GitHub to refresh the badge more frequently, you can append a cache-busting query parameter:

In practice, GitHub re-fetches badge images every few minutes for active repositories, so manual cache-busting is rarely needed.

The Public Status Page

When visitors click the badge, they land on a public status page at crontiq.io/public/{token}. This page displays:

• Current monitor status with a colored indicator
• Time since last ping
• Sparkline charts showing recent ping history
• Metric values from JSON payloads (if any)

No login is required. The public token (cq_chk_) provides read-only access to the monitor status. It cannot be used to send pings, modify settings, or access other monitors on your account.