Unix Timestamp Reference
A Unix timestamp represents an instant as elapsed time from 1970-01-01T00:00:00Z. The unit is part of the contract: seconds and milliseconds describe radically different dates when confused.
Common units
| Unit | Typical current magnitude | Conversion |
|---|---|---|
| Seconds | 10 digits | Milliseconds ÷ 1,000 |
| Milliseconds | 13 digits | Seconds × 1,000 |
| Microseconds | 16 digits | Seconds × 1,000,000 |
| Nanoseconds | 19 digits | Seconds × 1,000,000,000 |
Digit count is a useful diagnostic near the present, not a permanent parser rule. Document the field name and unit explicitly, such as created_at_ms, or use a typed schema with a clear description. Never guess units silently for security token expiry or financial event ordering.
UTC and time zones
A timestamp identifies an instant and does not carry a local time zone. Convert it to a zoned date only for display or calendar rules. The same instant appears with different wall-clock values in Istanbul, London, and New York. Store the originating zone separately when a future event must retain a local civil time such as “09:00 Europe/Istanbul.”
ISO 8601 and RFC 3339 representations
APIs often use an RFC 3339 date-time string such as 2026-07-28T00:00:00Z. The trailing Z denotes UTC; a numeric offset denotes another local representation of an instant. Include an offset for timestamps and avoid ambiguous strings without zone information. Calendar dates such as birthdays should remain dates, not midnight timestamps that shift under conversion.
Precision and numeric limits
JavaScript numbers exactly represent integers only through a finite safe range, so nanosecond epoch counts exceed exact integer precision. Use a string or bigint-aware contract when required. A signed 32-bit seconds value overflows in January 2038. Databases, drivers, and embedded systems should use wider types for future dates.
Negative timestamps and leap seconds
Systems can represent instants before the epoch with negative values, but library and database support varies. Unix time commonly treats days as 86,400 seconds and does not encode leap seconds as distinct labels. Use an authoritative time library and synchronization source rather than implementing calendar arithmetic manually.
Expiry and duration calculations
For JWT and cache expiry, compare values in the same unit and allow only a small documented clock skew. Use monotonic clocks for measuring elapsed durations inside a process so wall-clock corrections do not produce negative or inflated latency. Persist real instants with a wall-clock representation; a monotonic value has meaning only within its clock domain.
Frequently Asked Questions
Are timestamps always seconds?
No. The API must document its unit.
Do timestamps contain zones?
No. Apply a zone only when formatting an instant.
What is the 2038 problem?
A signed 32-bit seconds value overflows.