Unix Timestamp: Seconds vs Milliseconds
The single most common timestamp bug is treating a seconds-based value as milliseconds, or vice versa — the result is a date off by a factor of 1000, which usually lands somewhere absurd like 1970 or the year 50,000+.
Where each convention comes from
The Unix epoch itself is defined in seconds since January 1, 1970 UTC — that's the original, POSIX-defined unit, and what languages like Python (time.time()) and most Unix tools return by default. JavaScript's Date.now() and new Date().getTime(), however, return milliseconds — a JavaScript-specific choice baked into the language since its creation. Both are "Unix timestamps"; they just disagree on unit, and nothing in the raw number itself states which one it is.
How to tell which one you have
Count the digits:
- 10 digits (e.g.
1735689600) → almost certainly seconds. Ten-digit second timestamps cover roughly 2001–2286. - 13 digits (e.g.
1735689600000) → almost certainly milliseconds.
This heuristic works for essentially all real-world dates (anything after 2001 and before the year 2286), which covers nearly every timestamp you'll encounter.
Avoiding the bug in code
When consuming a timestamp from an API you don't control, don't assume — check the field name (_ms, _seconds suffixes are common) or the digit count before converting. When producing timestamps for others, document the unit explicitly rather than relying on convention, since different ecosystems disagree.
Convert one now
Cryonel's Timestamp Converter lets you pick the unit explicitly and shows both UTC and your local time, so you're never guessing.
Validate edge cases
Digit count is a useful modern-date heuristic, not a permanent type system. Dates before September 2001 can have nine-digit second values, negative values represent dates before 1970, and microsecond or nanosecond APIs produce longer numbers. Decimal seconds may preserve subsecond precision. The durable fix is to name the unit in the field or schema and test a known instant at the integration boundary.
Keep storage and display separate. An epoch value represents an instant relative to UTC and does not carry a local timezone. Convert it to the user's timezone only when formatting. If a date appears in 1970 or thousands of years in the future, check for an accidental multiply or divide by 1,000 before investigating timezone logic.
Frequently Asked Questions
Are Unix timestamps seconds or milliseconds?
POSIX uses seconds; some platforms and APIs use milliseconds, so the contract must state the unit.
How can I identify the unit?
Ten versus thirteen digits is a useful modern-date clue, but confirm with documentation or a known value.
Do epoch values include a timezone?
No. They represent an instant; timezone matters only when formatting it.