---
title: "Use this when you need to convert a value between units within one category (length, weight, temperature, volume, data, speed, area, time) instead of doing conversion arithmetic yourself."
method: POST
path: "/v1/convert_units"
tags: ["data"]
---

# Use this when you need to convert a value between units within one category (length, weight, temperature, volume, data, speed, area, time) instead of doing conversion arithmetic yourself.

`POST /v1/convert_units`

## Request

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

Use this when you need to convert a value between units within one category (length, weight, temperature, volume, data, speed, area, time) instead of doing conversion arithmetic yourself. Deterministic: same input, same output. Temperature uses the correct offset formulas (Celsius/Fahrenheit/Kelvin), not a naive ratio, and unit keys are case-sensitive (e.g. km, lb, celsius, MB) while the category name is case-insensitive. Example: {category:'length', value:5, from:'km', to:'mile'} -> result 3.10685596119. Returns the echoed category/value/from/to plus the converted result, rounded to 12 significant figures (switching to exponential for very large or very small magnitudes).

## Request body

- object
  - `category` 'length' | 'weight' | 'temperature' | 'volume' | 'data' | 'speed' | 'area' | 'time', required: Unit category.
  - `value` number, required: The numeric value to convert.
  - `from` string, required: Source unit key (e.g. km, lb, celsius, MB).
  - `to` string, required: Target unit key.

## Response `200`

Structured tool result.

- object
  - `tool` string
  - `result` object
    - `category` 'length' | 'weight' | 'temperature' | 'volume' | 'data' | 'speed' | 'area' | 'time', required: Echo of the unit category, lowercased.
    - `value` number, required: Echo of the input value (coerced to a number).
    - `from` string, required: Echo of the source unit key.
    - `to` string, required: Echo of the target unit key.
    - `result` number, required: Converted value, rounded to 12 significant figures (magnitudes >= 1e15 or < 1e-10 use exponential rounding to ~7 significant figures).

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