A Unix timestamp represents time as a count from an epoch, commonly the Unix epoch at 1970-01-01 00:00:00 UTC. When a log value looks like a long integer, first determine its unit: seconds, milliseconds, microseconds, and nanoseconds produce very different dates. Then convert the instant to UTC before comparing it with a local clock or another service.
Check the unit before converting
A timestamp of 1700000000 is plausibly epoch seconds; 1700000000000 is plausibly milliseconds. This is a heuristic, not a guarantee. A domain-specific field may use another epoch or precision. Check the API specification, column name, sample range, and producing code before assuming the unit.
A common bug is passing milliseconds to a function expecting seconds, or seconds to one expecting milliseconds. The result may land thousands of years away or near the start of 1970. A rough magnitude check catches many mistakes, but document the unit explicitly in the schema, such as created_at_ms or an ISO 8601 string with a timezone.
Microsecond and nanosecond values need more care. JavaScript Date stores time at millisecond precision, so converting a higher-resolution value may discard precision. Keep the original integer or decimal representation if sub-millisecond ordering matters.
Convert to an instant, then format it
A timestamp identifies an instant. A time zone controls how that instant is displayed. UTC is the clearest common reference for comparing events across systems; local time is useful to a person but can obscure the shared instant.
For example, if a service records 1700000000 seconds, multiply by 1,000 before passing it to JavaScript’s Date constructor, which accepts milliseconds since the epoch:
const seconds = 1700000000;
const date = new Date(seconds * 1000);
console.log(date.toISOString());
toISOString() displays a UTC timestamp ending in Z. A local formatter may show a different clock time because of the viewer’s timezone. That does not mean the underlying event changed.
Use Toolsnix’s Unix Timestamp Converter to inspect a value, but verify whether the input expects seconds or milliseconds and confirm the timezone displayed. Do not paste private production logs if they include customer identifiers or tokens.
Diagnose a time mismatch systematically
When two systems disagree about an event time, compare these details:
- Raw value: What exact number or string was emitted?
- Unit and precision: Seconds, milliseconds, or finer precision?
- Epoch: Unix epoch, application-specific epoch, or a relative duration?
- Timezone: Is the text UTC (
Z), an explicit offset, or an assumed local time? - Serialization: Was a numeric value rounded, parsed as a string, or converted twice?
- Clock source: Could the producing system’s clock be inaccurate or unsynchronized?
- Ordering: Are events sorted by timestamp, ingestion time, or a separate sequence number?
Write down the expected instant in ISO 8601 with Z or an explicit offset. This avoids ambiguous values such as 2026-10-26 09:00, which omit both timezone and possibly locale convention.
Seconds and milliseconds in common systems
Different systems choose different representations. Unix command-line tools often display seconds; JavaScript dates commonly use milliseconds; APIs may use integer seconds, millisecond integers, or ISO strings. Never infer solely from language or vendor: inspect the documentation and actual field contract.
A JSON number can exceed precision limits in some programming environments. JavaScript’s number type cannot represent every large integer exactly. If a service sends nanoseconds in a large integer, parsing it as a floating-point number can lose low-order digits. A string or a big-integer-aware representation may be needed. Check the API’s recommended client handling before converting.
Also distinguish an absolute timestamp from a duration. 3000 could mean 3,000 seconds after an event, a timestamp in a custom unit, or just a count. The field name and schema should make this explicit.
Handle daylight saving and timezone display carefully
Unix timestamps count from an absolute epoch and do not themselves carry a local timezone. Daylight-saving rules affect local formatting, not the numeric instant. If a local time is ambiguous during a clock change, preserve the offset or UTC instant in logs so an event can be ordered reliably.
For human-facing reports, display the timezone label or offset. “1:30 AM” without a date, location, and offset can refer to more than one instant in some regions. For system-to-system exchange, prefer a documented standard such as an ISO 8601 timestamp with timezone or a numeric timestamp whose unit is specified.
Common conversion mistakes
- Multiplying by 1,000 twice. Keep the unit in a variable name and convert at one boundary.
- Assuming every 13-digit number is milliseconds. Validate the schema and plausible date range.
- Comparing local clock strings from different machines. Convert to UTC or compare the original instants.
- Ignoring rounding. A displayed date may omit fractional seconds that exist in the stored value.
- Confusing event time with ingestion time. A delayed log can arrive after a later event; compare the correct field.
- Converting malformed input silently. Validate type, range, and unit, and show a clear error instead of rendering a misleading date.
Be explicit about timestamp contracts
A field named time does not tell a client what it means. Document whether it is an absolute timestamp or a duration, the epoch, unit, timezone, precision, and whether a missing value is allowed. For external APIs, ISO 8601 strings with an explicit Z or offset can make timezone intent easier to inspect, while numeric timestamps can be compact and efficient. Either choice needs a stable contract.
If one system stores milliseconds and another stores seconds, convert at a boundary and make that boundary obvious in code. Avoid ambiguous variable names such as timestamp. Prefer createdAtMs or a domain type that records the unit. A single conversion helper reduces the chance that different handlers multiply or divide inconsistently.
Distinguish event time from processing time
Distributed systems often have several relevant times: when an event occurred, when a service received it, when it was written to a log, and when a consumer processed it. These can differ because of network delay, retries, offline devices, or clock skew. Preserve separate fields when the distinction matters.
For example, a mobile device may record an event while offline and upload it later. Sorting only by ingestion time would make the event appear newer than actions that actually occurred afterward. Conversely, a device clock may be wrong, so event time alone may not be trustworthy. Use sequence numbers or server-assigned ordering where the domain requires it.
Validate ranges and failures
Reject or flag values that are malformed, outside the supported range, or implausible for the field. Do not silently convert an invalid string to a zero date. If an API accepts timestamps from users, define what to do with negative values, decimals, empty values, and excessively large numbers. The fallback should be documented and visible.
When comparing logs from multiple systems, account for clock synchronization and precision. Two events recorded at the same millisecond may have occurred in a different order; use causal IDs or sequence information if exact ordering is necessary. Do not infer causality from timestamps alone.
Handle dates that are not Unix timestamps
Some APIs return ISO 8601 strings such as 2026-10-26T12:30:00Z; these already include a timezone marker. Others return a date without an offset, which may be interpreted in the consumer’s local timezone. Do not convert an ISO string as if it were an epoch integer. Parse it according to the documented format and preserve the offset when it matters.
A timestamp may also be a relative duration, such as “retry after 30 seconds,” or a count measured from the start of a process. These values can look numeric but are not Unix time. Look at the field name and API schema. A field named expires_in usually describes a duration in a specific API contract, not a calendar instant.
Avoid date-only ambiguity
A date such as 2026-10-26 identifies a calendar date, not necessarily a single instant. If a system converts it to midnight in one timezone and another system interprets it in another, records can appear to belong to different days. Decide whether the business concept is a date (such as a billing day) or an instant (such as a payment event) and represent it accordingly.
For scheduled events, store the intended local timezone as well as the local date and time when that is the meaning. Converting to UTC is useful for execution and comparison, but a recurring appointment at 9 AM local time is not necessarily the same UTC hour throughout the year. Keep the timezone rules in the application’s schedule model.
Build assertions around real examples
Add tests for one known epoch value, one value at the expected precision, a value with a timezone offset, a daylight-saving boundary if relevant, an invalid string, and an out-of-range number. Assert both the parsed instant and the formatted output. This makes unit assumptions visible when a client library or serialization format changes.
For production debugging, preserve the original field and its metadata in logs when privacy policy allows. A normalized UTC value helps comparison, but retaining the source value and unit can reveal whether the conversion was performed twice or with the wrong assumption.
Treat parsing as an API boundary
Timestamp conversion should validate before formatting. A value can be syntactically numeric but outside the supported range, or a string can contain extra whitespace and a timezone abbreviation your parser interprets inconsistently. Return a clear error when input is invalid rather than showing a plausible but incorrect date.
When accepting user-entered timestamps, state whether decimals are allowed and how they are rounded. Preserve precision if it carries meaning; otherwise document the truncation. For public APIs, include examples in the schema and use names that communicate unit and meaning so a client does not need to guess from digit count.
Keep human display separate from stored time
Store an instant in a consistent representation and format it for the viewer’s locale at the presentation layer. This avoids persisting a localized string that another service cannot interpret reliably. When exporting a report, include a timezone or state the timezone in the report heading.
For systems that interact with leap seconds, specialized scientific clocks, or historical time standards, ordinary Unix timestamp assumptions may not be sufficient. Follow the domain’s timekeeping specification and flag the conversion for expert review. Most web applications can use documented UTC instants, but precision-critical domains should not silently simplify their time model.
FAQs
Are Unix timestamps always in seconds?
No. Many systems use milliseconds or finer precision. Check the field’s documentation and producing code before conversion.
Why does the same timestamp show different clock times?
The instant can be formatted in different time zones. Compare UTC or explicit offsets to determine whether the underlying timestamp differs.
Can JavaScript represent nanosecond timestamps exactly?
Not as an ordinary Number in general. JavaScript Date uses milliseconds, and large integers can lose precision. Use the API’s recommended representation if finer precision matters.
What is the Unix epoch?
It is the conventional reference instant of 1970-01-01 00:00:00 UTC for Unix time. Some systems use different epochs or specialized time scales, so verify nonstandard formats.
Next step
Record the timestamp’s unit, convert it once to UTC, and compare the resulting instant with the event’s source and ingestion times. If you control the API, document the unit in the field contract.