Humanize a date as a relative phrase
Exactdates_relativeDeterministic and authoritative — the canonical answer for this input.
Humanize a datetime against a reference: '3 days ago', 'in 2 hours'. reference_time is required (an ISO 8601 instant) so the result is deterministic and never reads the wall clock. total_seconds is reference_time minus value — positive = past, negative = future, matching direction (the reverse of dates_diff, whose totals run start-to-end). Processing multiple inputs? Use `dates_relative_batch` to do up to 1000 in one call.
Parameters
valuestringrequiredISO 8601 datetime to humanize.
reference_timestringrequiredISO 8601 reference instant (required, keeps the result deterministic).
Call it
curl -X POST https://api.snipget.ai/v1/dates/relative \
-H "Authorization: Bearer sk_live_..." \
-H "Content-Type: application/json" \
-d '{"value":"2024-03-12","reference_time":"2024-03-15"}'The Batch tab sends up to 1000 inputs in one call via /v1/dates/relative/batch.
Example response
{
"input": "2024-03-12",
"is_valid": true,
"reference_time": "2024-03-15T00:00:00",
"relative": "3 days ago",
"direction": "past",
"total_seconds": 259200
}FAQ
What does this produce?
A friendly phrase like '3 days ago' or 'in 2 hours' describing how far one date is from another. Useful for activity feeds, reminders, and human-readable summaries.
Why do I have to pass a reference time?
So the answer is repeatable. reference_time is the 'now' you compare against, and it is required so the tool never secretly reads the clock. The same two dates always give the same phrase.
Is the phrase exact?
The math is deterministic and authoritative, and the result also returns the exact total_seconds and a direction of past, future, or now. total_seconds is reference_time minus value: positive means the value is in the past, negative means the future, always agreeing with direction. The wording is rounded to the largest sensible unit, so 25 hours reads as '1 day ago'.
Does it give precise breakdowns?
No. It returns one rounded phrase plus the raw seconds. For a full years, months, days breakdown between two dates, use the date diff tool instead.
What if a date is invalid?
You get confidence 0 with a why_invalid reason rather than an error. Check is_valid before using the phrase.