Duration Format API: The Complete Guide to Time Duration Formatting

Need to display time durations in a user-friendly format? This guide covers everything you need to know about formatting durations via API, including various output formats and implementation examples in multiple languages.

What is Duration Formatting?

Duration formatting converts raw time values (milliseconds, seconds) into human-readable strings that users can easily understand. For example, 9015000 milliseconds becomes "2h 30m 15s" or "2 hours, 30 minutes".

Users understand "2 hours ago" much better than "7200000 ms".

Format Styles

Different styles suit different contexts:

Short Format

2h 30m 15s - Compact, good for dashboards and limited space.

Long Format

2 hours, 30 minutes, 15 seconds - More readable, better for descriptions.

Digital Format

02:30:15 - Clock-style, familiar from timers and video players.

Approximate Format

"about 2 hours" - Simplified, used when precision isn't critical.

Using the Duration Format API

TinyFn provides a simple endpoint to format durations:

GET https://api.tinyfn.io/v1/format/duration?ms=9015000
Headers: X-API-Key: your-api-key

{
  "milliseconds": 9015000,
  "short": "2h 30m 15s",
  "long": "2 hours, 30 minutes, 15 seconds",
  "digital": "02:30:15",
  "components": {
    "hours": 2,
    "minutes": 30,
    "seconds": 15,
    "milliseconds": 0
  }
}

Parameters

Code Examples

JavaScript / Node.js

// Format duration in milliseconds
const response = await fetch(
  'https://api.tinyfn.io/v1/format/duration?ms=9015000',
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const { short, long, digital } = await response.json();
console.log(short);   // 2h 30m 15s
console.log(long);    // 2 hours, 30 minutes, 15 seconds
console.log(digital); // 02:30:15

// Show only 2 largest units
const compactResponse = await fetch(
  'https://api.tinyfn.io/v1/format/duration?ms=9015000&largest=2',
  { headers: { 'X-API-Key': 'your-api-key' } }
);
const { short: compact } = await compactResponse.json();
console.log(compact); // 2h 30m

Python

import requests

# Format duration
response = requests.get(
    'https://api.tinyfn.io/v1/format/duration',
    params={'ms': 9015000},
    headers={'X-API-Key': 'your-api-key'}
)
data = response.json()
print(data['short'])   # 2h 30m 15s
print(data['long'])    # 2 hours, 30 minutes, 15 seconds
print(data['digital']) # 02:30:15

# Format from seconds
response = requests.get(
    'https://api.tinyfn.io/v1/format/duration',
    params={'seconds': 3661},
    headers={'X-API-Key': 'your-api-key'}
)
print(response.json()['short'])  # 1h 1m 1s

cURL

# Format duration in milliseconds
curl "https://api.tinyfn.io/v1/format/duration?ms=9015000" \
  -H "X-API-Key: your-api-key"

# Format with 2 largest units only
curl "https://api.tinyfn.io/v1/format/duration?ms=9015000&largest=2" \
  -H "X-API-Key: your-api-key"

Common Use Cases

• Video Players: Display video length and playback position
• Task Timers: Show elapsed time on tasks and projects
• Build Systems: Display build and deployment times
• Analytics: Show session duration and time-on-page
• Countdowns: Display time remaining until events

Best Practices

1. Match context: Use digital format for media, short for metrics
2. Limit precision: Don't show seconds for multi-hour durations
3. Handle zero: Display "0s" or "instant" rather than empty string
4. Consider localization: Different languages use different abbreviations

Use via MCP

Your AI agent can call this tool directly via Model Context Protocol — no HTTP code needed. Add TinyFn to Claude Desktop, Cursor, or any MCP client:

{
  "mcpServers": {
    "tinyfn-format": {
      "url": "https://api.tinyfn.io/mcp/format/",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

See all formatting tools available via MCP in our Formatting MCP Tools for AI Agents guide.