---
title: "Use this when you need to convert a wall-clock date-time between IANA time zones with correct DST handling."
method: POST
path: "/v1/convert_timezone"
tags: ["datetime"]
---

# Use this when you need to convert a wall-clock date-time between IANA time zones with correct DST handling.

`POST /v1/convert_timezone`

## Request

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

Use this when you need to convert a wall-clock date-time between IANA time zones with correct DST handling. Prefer this over doing timezone math yourself (a documented LLM failure mode): it uses the runtime's IANA database so offsets and daylight-saving transitions are exact. Deterministic: same input, same output. Returns the corresponding UTC instant, both zones' UTC offsets in minutes at that instant, and the converted local time. Example: {datetime:'2026-07-08T14:30', fromTz:'America/New_York', toTz:'Asia/Tokyo'} -> converted '9 Jul 2026, 03:30:00' (UTC 2026-07-08T18:30:00.000Z).

## Request body

- object
  - `datetime` string, required: Local date-time in the source zone, ISO form YYYY-MM-DDTHH:MM.
  - `fromTz` string, required: Source IANA zone, e.g. America/New_York.
  - `toTz` string, required: Target IANA zone, e.g. Asia/Tokyo.

## Response `200`

Structured tool result.

- object
  - `tool` string
  - `result` object
    - `input` string, required: Echo of the source wall-clock datetime.
    - `fromTz` string, required: Source IANA time zone.
    - `toTz` string, required: Target IANA time zone.
    - `utc` string, required: The corresponding UTC instant, ISO-8601.
    - `fromUtcOffsetMinutes` integer, required: Source zone's UTC offset in minutes at that instant (e.g. -240 for EDT).
    - `toUtcOffsetMinutes` integer, required: Target zone's UTC offset in minutes at that instant (e.g. 540 for JST).
    - `converted` string, required: Wall-clock time in the target zone, e.g. '9 Jul 2026, 03:30:00'.

## 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)