---
title: "Use this when you have a timestamp in one form (unix epoch seconds/milliseconds/microseconds, or an ISO-8601 date-time) and need it in the others, or rendered in a specific IANA time zone."
method: POST
path: "/v1/convert_timestamp"
tags: ["datetime"]
---

# Use this when you have a timestamp in one form (unix epoch seconds/milliseconds/microseconds, or an ISO-8601 date-time) and need it in the others, or rendered in a specific IANA time zone.

`POST /v1/convert_timestamp`

## Request

- Base URL: `https://api.clean.tools`
- URL: `https://api.clean.tools/v1/convert_timestamp`
- Auth: none declared

Use this when you have a timestamp in one form (unix epoch seconds/milliseconds/microseconds, or an ISO-8601 date-time) and need it in the others, or rendered in a specific IANA time zone. Auto-detects the input: a number or digit-string is an epoch classified by length (~10 digits = seconds, ~13 = milliseconds, ~16 = microseconds); anything else is parsed as ISO-8601, with a naive date-time (no Z/offset) taken as UTC. Returns unix_s, unix_ms, iso_utc, iso_tz (with numeric offset), a human string, and the weekday, all in the requested zone (default UTC), correctly handling DST transitions and pre-1970 (negative) epochs. Deterministic: same input, same output. Prefer this over doing epoch/timezone arithmetic yourself. Example: { value: 1783454640, timezone: "America/Chicago" } -> iso_utc "2026-07-07T20:04:00.000Z", human "Tuesday, July 7, 2026 at 3:04 PM CDT".

## Request body

- object
  - `value` union, required: The timestamp to convert: a unix epoch (number or digit-string; seconds/milliseconds/microseconds auto-detected by length) or an ISO-8601 date-time (e.g. "2026-07-07T15:04:00-05:00" or "2026-07-07"). A naive date-time with no zone designator is interpreted as UTC.
    - string
    - number
  - `timezone` string: IANA time zone used to render iso_tz, human, and weekday, e.g. "America/Chicago". Defaults to "UTC".

## Response `200`

Structured tool result.

- object
  - `tool` string
  - `result` object
    - `detected` 'seconds' | 'milliseconds' | 'microseconds' | 'iso', required: How the input was classified: an epoch band chosen by digit length, or 'iso' when parsed as a date-time string.
    - `timezone` string, required: IANA time zone used to render iso_tz, human, and weekday (echo of input; default 'UTC').
    - `unix_s` integer, required: Unix epoch in whole seconds (negative for pre-1970 instants).
    - `unix_ms` integer, required: Unix epoch in milliseconds.
    - `iso_utc` string, required: The instant in UTC, ISO-8601 with milliseconds and a trailing 'Z'.
    - `iso_tz` string, required: The instant rendered in the requested zone, ISO-8601 with a numeric offset (e.g. '-05:00').
    - `human` string, required: Human-readable local time with weekday, date, time, and zone abbreviation.
    - `weekday` string, required: Day of week in the requested zone, e.g. 'Tuesday'.

## Other responses

- `400`: Invalid input or the tool reported an error.
- `413`: Request body exceeds the 128 KB limit.
- `429`: Rate limit exceeded; the response carries Retry-After and RateLimit-* headers — honor them and add jitter.

---

[API](https://skmtc.dev/clean/apis/clean-tools-api.md) · [All operations](https://skmtc.dev/clean/apis/clean-tools-api/llms.txt) · [OpenAPI document](https://skmtc.dev/clean/apis/clean-tools-api/revisions/a24a01d2833c?raw)