Unix timestamps are compact, machine-friendly values, but a seconds-versus-milliseconds mismatch can make a valid date look wildly wrong. This guide explains how to convert Unix time, recognize seconds and milliseconds, compare ISO 8601 and RFC 3339 values, account for time zones, and debug timestamps across APIs, logs, databases, JavaScript, and monitoring systems.
Overview
A Unix timestamp, also called epoch time, represents a point in time as an offset from 1970-01-01T00:00:00Z. The most common forms are:
- Unix seconds: whole or fractional seconds since the Unix epoch. A current value often has 10 digits before the decimal point.
- Unix milliseconds: milliseconds since the epoch. A current value often has 13 digits.
- ISO 8601 or RFC 3339: a human-readable date such as
2026-11-05T14:30:00Zor2026-11-05T14:30:00+00:00. - Database timestamps: a native date or timestamp type whose display and storage behavior depends on the database and query settings.
The digit-count rule is a useful first check, not proof. Timestamps for older or future dates may have fewer or more digits, and some systems use microseconds or nanoseconds. Always confirm the unit from the API contract, schema, SDK, log format, or surrounding code before changing data.
| Format | Example | Typical use |
|---|---|---|
| Unix seconds | 1793889000 | APIs, authentication claims, command-line tools |
| Unix milliseconds | 1793889000000 | JavaScript dates, browser events, telemetry |
| ISO 8601 UTC | 2026-11-05T14:30:00Z | Logs, APIs, documentation |
| RFC 3339 with offset | 2026-11-05T14:30:00-05:00 | Interoperable date-time text |
What to track
Unit, precision, and direction
When investigating a timestamp, record four properties: the numeric value, its unit, its precision, and the time zone or offset used for display. A value ending in three fractional digits may indicate milliseconds in a decimal-seconds format, while a 13-digit integer usually indicates milliseconds. Microsecond and nanosecond values are larger still. Do not divide or multiply a value until you know which convention the producer uses.
The conversion direction matters. To turn Unix milliseconds into Unix seconds, divide by 1,000. To turn seconds into milliseconds, multiply by 1,000. Preserve fractional precision when it carries information required for ordering events. Rounding timestamps can make two closely spaced events appear simultaneous.
Time zone and offset
Unix timestamps identify an instant and are normally interpreted relative to UTC. A local date-time without an offset does not identify one unambiguous instant. For example, 09:00 could refer to different moments in different locations. Prefer values ending in Z for UTC or values with an explicit offset such as +02:00.
Keep the original timestamp and the converted display value together in incident notes. This makes it possible to reproduce a comparison after a developer changes their local time zone or after daylight-saving rules affect a local display.
Runtime and storage behavior
JavaScript's Date constructor expects a Unix-style numeric value in milliseconds. Passing seconds directly can therefore produce an incorrect result. A defensive conversion can make the unit explicit:
const seconds = 1793889000;
const date = new Date(seconds * 1000);
console.log(date.toISOString());
In Python, use an explicit unit and UTC-aware output:
from datetime import datetime, timezone
timestamp = 1793889000
date = datetime.fromtimestamp(timestamp, tz=timezone.utc)
print(date.isoformat())
For SQL, check whether the database function expects seconds, milliseconds, or a native timestamp. Do not assume that a column called created_at has a universal meaning. Inspect the schema, sample values, and query documentation before comparing it with an API response.
Cadence and checkpoints
Use a repeatable checkpoint whenever you compare timestamps across systems:
- Capture the raw value. Copy the exact API field, log line, database value, or token claim. Avoid relying only on a formatted dashboard label.
- Identify the unit. Check the contract and code first, then use digit length as a sanity check. Test a known event when possible.
- Convert to one canonical representation. ISO 8601 in UTC is practical for notes and tickets; retain the original numeric value alongside it.
- Compare instants, not clock text. Convert offsets before deciding that two records disagree.
- Measure the difference. Record whether the gap is milliseconds, seconds, minutes, or hours. The size often points to a unit, clock, or time-zone problem.
- Check ordering and boundaries. Look for ingestion delays, retries, truncation, rounding, and expiration boundaries.
For recurring operational checks, review timestamp handling monthly or quarterly in the services that produce important events. Confirm that API examples, log parsers, dashboards, scheduled jobs, and database queries still use the intended unit. A lightweight test should verify a known instant in seconds and milliseconds, including a value with fractional precision if the system supports it.
This workflow complements broader debugging checks. When a webhook appears late, compare delivery and application timestamps using the webhook debugging guide. When an API record does not match stored data, validate its structure and types with the JSON Schema validation guide.
How to interpret changes
A date far in the past or future
The usual causes are a seconds/milliseconds mismatch, an accidental conversion performed twice, or a value interpreted as microseconds or nanoseconds. Test the raw number at each plausible scale and compare the result with a known event. If only some records are wrong, inspect whether different producers use different units.
Exactly one or several hours apart
An offset or daylight-saving display issue is more likely than a Unix conversion error. Check whether one system emits UTC while another renders local time. Compare the explicit offset and the underlying instant, not just the date shown in a user interface.
Events appear out of order
Separate event time from ingestion, processing, and display time. Distributed systems can receive an older event after a newer one, and clocks on different hosts may not agree perfectly. Include a request ID, host or service name, and all available timestamp fields when reconstructing a sequence.
Expiration values do not behave as expected
Authentication claims and cache metadata often use numeric epoch values. Verify the claim's unit, compare it with the current time in UTC, and account for permitted clock skew if the system documents one. A decoder can reveal a token's payload, but decoding does not validate its signature or establish that it is safe to trust.
When to revisit
Return to this guide whenever a service changes its API contract, logging library, database driver, runtime, monitoring integration, or scheduled-job implementation. Recheck it after a migration between JavaScript, Python, SQL, or other runtimes, because date constructors and formatting defaults differ. It is also worth revisiting during a quarterly observability review and before a system begins operating across additional regions or time zones.
Keep a small timestamp test case in the repository: one known UTC instant, its seconds representation, its milliseconds representation, and an offset-formatted equivalent. Run it when parsers or dependencies change. During an incident, write down the raw value, detected unit, UTC conversion, local display, and source system before making a correction. That simple record prevents a temporary conversion workaround from becoming a permanent data error.
For a practical next step, use a browser-based Unix timestamp converter to check a suspicious value, then verify the result in the runtime or database that produced it. Treat the online result as a fast diagnostic, not a substitute for confirming the producer's documented format.