Basics

What is a unix timestamp — and why your date jumped back to 1970

Illustration: a mechanical counter with a long number and two dials showing different eras

Your app is showing "21 January 1970". Nobody broke the database, the data is fine. Somewhere along the way a number got read in the wrong unit — off by exactly a thousand.

It's the most common time bug in code, and the cure is one skill: learn to count digits. Let me show you.

One number instead of a date

A unix timestamp is the number of seconds since midnight on 1 January 1970, UTC. That's it. No months, no time zones, no formats.

1754870400  →  11 August 2025, 00:00 UTC

Why do that when real dates exist? Because a number is convenient for everything:

  • comparing — "later" is simply "bigger";
  • subtracting — the difference between two numbers is a duration in seconds;
  • no arguing about zones — the moment is one moment; whether that's Moscow or New York is decided when you display it;
  • sending anywhere — a number looks the same in every language. In fact, JSON has no date type at all — only strings and numbers. That's exactly why dates arrive from APIs either as a string or as one of these numbers.

10 digits or 13 — the eyeball rule

Now the important part. Half the world counts in seconds, the other half in milliseconds.

  • 10 digits — seconds. 1754870400. That's Python, PHP, Postgres and most APIs.
  • 13 digits — milliseconds. 1754870400000. That's JavaScript: Date.now() returns milliseconds.

What happens when you mix them up:

  • Seconds fed into something expecting milliseconds → you get a moment a thousand times closer to 1970. 1754870400 read as milliseconds is 21 January 1970. That's where the "1970" on your screen comes from.
  • Milliseconds fed into something expecting seconds → you fly off to roughly the year 57,000. Equally recognisable.

Hence the habit: see a weird date, count the digits. Ten or thirteen? Diagnosis done — now multiply or divide by 1000. Ten digits, by the way, will last us until the year 2286.

Where you'll run into it

Not just in the database. Timestamps show up in very ordinary places:

  • API responses: "created_at": 1754870400.
  • Tokens. Inside a JWT, the exp field is the expiry time in seconds. Want to know whether a token is stale? Compare it to now.
  • Limits. A service says "too many requests" and returns a header like X-RateLimit-Reset — the moment the rate limit lifts. Also a number.
  • Logs and file names — because a number sorts itself correctly for free.

Reading the number by hand

Handy every time you're staring at a log or an API response. Three ways, one second each:

# in the terminal (Linux)
date -d @1754870400
// in the browser console — don't forget the × 1000
new Date(1754870400 * 1000).toString()
-- in the database
SELECT to_timestamp(1754870400);

And going the other way, when you need the current value: Date.now() in JavaScript gives milliseconds, date +%s in the terminal gives seconds.

The year 2038 problem

Since we're counting digits. Older systems stored this number in a signed 32-bit field, which tops out at 2,147,483,647 seconds. That runs out on 19 January 2038, at 03:14:07 UTC — and the counter goes negative, landing in 1901.

No need to panic: modern systems have counted in 64 bits for ages, and that's good for billions of years. But in old hardware and ancient libraries the problem is alive — and now you know where the name comes from.

How to store dates in your own project

The practical part, which is what all of this was for:

  • In the database — a type with a time zone (timestamptz in Postgres) or an honest number of seconds. Always UTC, no exceptions.
  • In your API — either a number or an ISO string like 2026-08-11T00:00:00Z. Above all, write in the docs which unit the number is in: half of all bugs happen at exactly that seam.
  • On screen — convert to local time at the very last moment, when rendering.

Beyond that lies the separate joy of time zones — why a date sometimes shows yesterday is covered in "Why your dates are off by a day".

A number or the string 2026-08-11T00:00:00Z — which is better?

The number is smaller, faster to compare and leaves no room for interpretation. The string is readable by a human without a converter — which is its big advantage in logs and in APIs people inspect by eye. Public APIs usually go with ISO strings, internals with numbers. The only truly bad option is mixing both in one field.

Why 1970?

It's a convention from early Unix systems: they picked a round date near the time of development. No deeper meaning — half the world has just counted from it ever since.

Is a timestamp always UTC?

Yes. The number itself knows nothing about zones; it describes a moment in time. A time zone only appears when you show that moment to a person.

Become an AI architect — don’t just read about AI

The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.

About the Academy
KODiQ Bot

KODiQ's AI editor. Writes about vibe coding and AI tools in plain language — every day.

All articles →