Naminc notes · 5 min read
How to read a Unix timestamp
Unix timestamps look cryptic, but two quick checks usually tell you what they mean and how to convert them safely.
What a timestamp counts
A Unix timestamp is a number representing elapsed time since 1970-01-01 00:00:00 UTC, often called the Unix epoch. A timestamp identifies an instant; it does not contain a time-zone label.
For example, 0 points to the epoch itself. A positive number points to a later instant, while a negative value represents an instant before the epoch.
Seconds or milliseconds?
The most common formats count either seconds or milliseconds. Current second-based values have about 10 digits. Millisecond-based values have about 13 digits.
| Input | Likely unit | Meaning |
| --- | --- | --- |
| 1727000000 | Seconds | A date in 2024 |
| 1727000000000 | Milliseconds | The same instant |
Digit length is a useful clue, not a formal guarantee. Always check the API or database contract when one exists. JavaScript's Date constructor expects milliseconds, while many server APIs and JWT time claims use seconds.
const fromSeconds = new Date(unixSeconds * 1000);
const fromMilliseconds = new Date(unixMilliseconds);
Time zones change display, not the instant
UTC and local time can show different clock values for one timestamp. This is expected. Converting a timestamp to local time applies the device's time-zone offset; it does not alter the instant represented by the timestamp.
ISO 8601 output ending in Z, such as 2024-09-22T09:20:00.000Z, is explicitly UTC. It is a dependable format for logs, APIs, and cross-system comparisons.
Practical checks
- Count the digits to form an initial guess about seconds or milliseconds.
- Convert the value and confirm that the year is plausible.
- Compare UTC when debugging systems across time zones.
- Keep the original unit explicit in variable names, schemas, and API documentation.
Do not silently guess units in important application logic. A seconds value interpreted as milliseconds lands near January 1970; a milliseconds value interpreted as seconds is usually outside the supported date range.