Build with How Long Until X

USAGE & PRICING

Free to start, pay only for scale

Every request against Countdown or Search consumes 1 credit. Credits reset monthly. The Free tier is enough for a personal site or a low-traffic widget; once you're past that, pick the tier that matches your volume — no per-call surprises.

Once a tier's monthly credits are used, further calls return 402 Payment Required until your credits reset or you upgrade. We'll email you at 80% and 100% usage so nothing breaks silently.

Authentication

The Free tier needs nothing — just call the endpoint. On Growth and Scale, pass your API key as a Bearer token. Requests with a valid key are billed to your plan's credits instead of the shared IP-based Free pool.

curl "https://howlonguntilx.com/api/countdown?event=christmas" \
  -H "Authorization: Bearer hlx_live_xxxxxxxxxxxxxxxx"

Subscribe to Growth or Scale above to get a key instantly via PayPal — a full key-management dashboard is coming soon, in the meantime your key is available at GET /api/keys while signed in.

Countdown

Returns the live time remaining until any event. Pass a known event slug from our database (e.g. a specific date already tracked on the site), or plain text — the API understands both shortcuts like christmas and natural dates like 2027-06-01 or "next friday".

Query parameters

Example request

curl "https://howlonguntilx.com/api/countdown?event=christmas"

const res = await fetch("https://howlonguntilx.com/api/countdown?event=christmas");
const data = await res.json();
console.log(data.days_left, "days left until", data.event);

import requests

r = requests.get("https://howlonguntilx.com/api/countdown", params={"event": "christmas"})
data = r.json()
print(f"{data['days_left']} days left until {data['event']}")

Example response

{
  "event": "Christmas",
  "target_date": "2026-12-25T00:00:00.000Z",
  "days_left": 147,
  "hours_left": 14,
  "minutes_left": 2,
  "seconds_left": 58,
  "progress_percent": 60,
  "is_past": false
}

Response fields

Errors

Search

Full-text search across tracked events and published tool articles. Handy for building a "jump to a countdown" search box, or for surfacing related pages from your own content.

Query parameters

Example request

curl "https://howlonguntilx.com/api/search?q=christmas"

const res = await fetch("https://howlonguntilx.com/api/search?q=christmas");
const results = await res.json();
results.forEach(r => console.log(r.type, r.name, r.href));

Example response

[
  {
    "slug": "christmas",
    "name": "Christmas",
    "category": "holidays",
    "type": "event",
    "href": "/how-long-until-christmas"
  },
  {
    "slug": "ces-2027-dates",
    "name": "CES 2027",
    "category": "tech-events",
    "type": "article",
    "href": "/tools/tech-events/ces-2027-dates"
  }
]

Response fields

Results are capped at 8, sorted by relevance (views for events, likes for articles).

Calendar

Unlike Countdown and Search, this endpoint is not public. It reads and writes a signed-in Pro user's own saved calendar days on howlonguntilx.com, authenticated via session cookie — it's what powers the "save this day" feature inside your own account, not something an outside site can call anonymously.

We're documenting it here for transparency and for anyone building an internal tool against their own account. If you're looking to pull public countdown data into your app, use Countdown instead.

Requests (must include a valid session cookie)

curl "https://howlonguntilx.com/api/calendar" \
  -H "Cookie: next-auth.session-token=<your-session-token>"

# → 200 { "days": [...] }  if Pro
# → 200 { "days": null }   if signed in but not Pro
# → 401 { "error": "Unauthorized" } if not signed in

curl -X POST "https://howlonguntilx.com/api/calendar" \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=<your-session-token>" \
  -d '{ "days": ["2026-12-25", "2027-01-01"] }'

# → 200 { "ok": true, "updatedAt": "..." }
# → 403 { "error": "Pro required" } if not on Pro plan