Developers

Countdown API

A free, public endpoint that tells you how long until signed 32-bit Unix time overflows. No API key, no sign-up, CORS enabled. Put a countdown in your terminal prompt, your status bar, your Discord bot or your conference slides.

GET https://epochalypse.org/api/countdown

Try it

format (leave blank for JSON)

Parameters

There is one optional query parameter.

Name	Type	Description
format	string	Leave it out (or blank, or `json`) to get a JSON object. Pass a preset name, or any string containing `{tokens}`, to get plain text back. Max 500 characters.

Default response (JSON)

curl https://epochalypse.org/api/countdown

{
  "target": "2038-01-19T03:14:08Z",
  "target_unix": 2147483648,
  "now": "2026-10-05T18:00:00.000Z",
  "now_unix": 1791223200,
  "now_int32": 1791223200,
  "overflowed": false,
  "percent_elapsed": 83.41033,
  "remaining": {
    "total_seconds": 356260448,
    "total_minutes": 5937674,
    "total_hours": 98961,
    "days": 4123,
    "hours": 9,
    "minutes": 14,
    "seconds": 8,
    "milliseconds": 0
  },
  "text": "4,123 days, 9 hours, 14 minutes, 8 seconds"
}

Field	Description
target	The overflow moment: the first second a signed 32-bit `time_t` can't hold.
target_unix	The same moment as Unix seconds: 2³¹.
now / now_unix	The server's current time.
now_int32	What a 32-bit clock reads right now. Once the overflow hits, this goes negative.
overflowed	`true` once the target has passed. All `remaining` values then stay at 0.
percent_elapsed	How much of the 32-bit range has been used since 1970.
remaining.days…seconds	Time left broken into days, hours (0–23), minutes (0–59) and seconds (0–59).
remaining.total_*	Time left expressed entirely in one unit.
text	A human-readable sentence.

Preset formats

These return text/plain.

format=	Example output
text	`4,123 days, 9 hours, 14 minutes, 8 seconds` (also accepts `string`, `plain`, `txt`)
clock	`4123:09:14:08`
seconds	`356260448`
iso	`P4123DT9H14M8S` (ISO 8601 duration)

Custom format strings

Anything that isn't a preset is treated as a template. Tokens in curly braces are replaced; everything else is returned as-is. Use {{ and }} for literal braces. Unknown tokens are left untouched. Remember to URL-encode the value.

Token	Meaning
{d}	Days remaining (same as `{D}`)
{h} {m} {s}	Hours (0–23), minutes (0–59), seconds (0–59)
{hh} {mm} {ss}	Same, zero-padded to two digits
{ms} {mss}	Milliseconds (0–999), and zero-padded to three digits
{H} {M} {S}	Total hours, total minutes, total seconds remaining
{unix}	Current Unix time in seconds
{now}	Current time, ISO 8601
{target}	`2038-01-19T03:14:08Z`
{text}	The human-readable sentence

Examples

Shell

curl "https://epochalypse.org/api/countdown?format=clock"
# 4123:09:14:08

curl -G "https://epochalypse.org/api/countdown" \
  --data-urlencode "format=T-minus {d} days, {hh}:{mm}:{ss}"
# T-minus 4123 days, 09:14:08

JavaScript

const res = await fetch('https://epochalypse.org/api/countdown');
const { remaining } = await res.json();
console.log(`${remaining.days} days to go`);

// or as plain text
const fmt = encodeURIComponent('{d} days until the Epochalypse');
const text = await (await fetch(`https://epochalypse.org/api/countdown?format=${fmt}`)).text();

Python

import requests

r = requests.get("https://epochalypse.org/api/countdown",
                 params={"format": "{S} seconds left"})
print(r.text)

Errors

Errors come back as JSON with an appropriate status code:

{ "error": "format must be 500 characters or fewer" }

Fair use

The API is free and has no key. Responses are never cached (the answer changes every second), so if you're displaying a live countdown, fetch once and count down locally rather than polling every second. The math is simple: the target is always Unix time 2147483648. Please don't hammer it. Abusive traffic may be rate-limited. Full terms are on the License & Terms page.