Elapsed since
GET /v1/time/elapsedOpenAPI YAMLTime between a reference timestamp and now (or a compare timestamp), with direction (passed or left).
What do I need to send?
Provide exactly one reference timestamp: unix, unix_ms, or iso.
compare_* fields replace now as the comparison point; business-day fields, format, and sign are optional.
Rule: direction is passed when the reference is earlier and left when it is still in the future.
| Name | Needed? | Use it for |
|---|---|---|
unix | Choose one input | Reference timestamp as Unix seconds. |
unix_ms | Choose one input | Reference timestamp as Unix milliseconds. |
iso | Choose one input | Reference timestamp as ISO 8601. |
source_tz | Conditional hint | Interpret a local iso= reference as wall time in this IANA zone. |
source_ip | Conditional hint | Interpret a local iso= reference using this IP address timezone. |
source_lat | Pair parameter | Latitude hint for local iso=. Pair with source_lon. |
source_lon | Pair parameter | Longitude hint for local iso=. Pair with source_lat. |
source_offset | Conditional hint | Interpret a local iso= reference against a fixed UTC offset. |
compare_unix | Choose one input | Optional comparison timestamp as Unix seconds instead of now. |
compare_unix_ms | Choose one input | Optional comparison timestamp as Unix milliseconds instead of now. |
compare_iso | Choose one input | Optional comparison timestamp as ISO 8601 instead of now. |
compare_source_tz | Conditional hint | Interpret a local compare_iso= timestamp as wall time in this IANA zone. |
compare_source_ip | Conditional hint | Interpret a local compare_iso= timestamp using this IP address timezone. |
compare_source_lat | Pair parameter | Latitude hint for local compare_iso=. Pair with compare_source_lon. |
compare_source_lon | Pair parameter | Longitude hint for local compare_iso=. Pair with compare_source_lat. |
compare_source_offset | Conditional hint | Interpret a local compare_iso= timestamp against a fixed UTC offset. |
tz | Choose one target | Accepted for symmetry: "now" is the same instant in every zone, so this does not change the result. Cannot be combined with compare_*. |
ip | Choose one target | Accepted for symmetry; does not change the result. Cannot be combined with compare_*. |
lat | Pair parameter | Accepted for symmetry with lon; does not change the result. |
lon | Pair parameter | Accepted for symmetry with lat; does not change the result. |
offset | Choose one target | Accepted for symmetry; does not change the result. Cannot be combined with compare_*. |
auto_tz | Choose one target | Accepted for symmetry; does not change the result. |
format | Optional | Duration template using %days %hours %minutes %seconds for an additional `formatted` field. |
business_days | Optional | Set true (or 1 / yes) to include a business_days count in the response. Counted by calendar date, start included, end excluded. |
holiday_country | Conditional | Holiday calendar: one of the 249 countries with holiday calendars (ISO 3166-1 alpha-2, e.g. FR, SA, CH), or a combined code such as CH-ZH or FR-6AE. Requires business_days=true. Full list: /docs#holiday-calendars. |
holiday_subdivision | Conditional | Subdivision code for the country, e.g. ENG (GB), ZH (CH), MH (IN), 01 (FI), 6AE (FR); digits and leading zeros are part of the code. Requires holiday_country and business_days=true. Full list: /docs#holiday-calendars. |
sign | Optional | Set true for a signed response. |
Code samples
Copy a request in your preferred language and replace YOUR_TIMELOGIC_API_KEY with your direct API key.
curl "https://api.timelogicapi.com/v1/time/elapsed?unix=1711300000" \
-H "Authorization: Bearer $TIMELOGIC_API_KEY"Example response
{
"seconds": 525695,
"minutes": 8761,
"hours": 146,
"days": 6,
"human": "146 hours, 1 minute, 36 seconds",
"direction": "passed"
}
Additional endpoint notes
Exactly one input form is required (unix, unix_ms, or iso).
https://api.timelogicapi.com/v1/time/elapsed?iso=2026-04-30T16:42:11Z
https://api.timelogicapi.com/v1/time/elapsed?unix=1711300000
# Compare two timestamps instead of using now
https://api.timelogicapi.com/v1/time/elapsed?iso=2026-01-01T00:00:00Z&compare_iso=2026-01-02T00:00:00Z
# → "seconds": 86400, "direction": "passed"
# Business days between the reference and the compare timestamp
https://api.timelogicapi.com/v1/time/elapsed?iso=2026-01-02T00:00:00Z&compare_iso=2026-04-30T00:00:00Z&business_days=true&holiday_country=FR
# → "business_days": 83
direction is passed if the reference is before the compared instant (now, or compare_*), and left if it is after. When the two instants are equal, elapsed returns seconds: 0 with direction: "passed" (/v1/time/diff returns same in that case).
seconds, minutes, hours and days are each the whole duration in that unit, and format placeholders (%days %hours %minutes %seconds) are totals, not remainders. human is written in hours, minutes and seconds.
Business days follow the same rules as diff: calendar dates, start included, end excluded, unsigned. The reference date is taken in its source_* zone and the compare date in its compare_source_* zone when given, otherwise in UTC. See Diff & business days.
The target selectors (tz, ip, lat/lon, offset, auto_tz) are accepted but cannot change the result, because "now" is the same instant everywhere. Combining one with a compare_* timestamp returns 400 AMBIGUOUS_TARGET.
Common errors
400 INVALID_TIMESTAMP— no input timestamp provided, or a timestamp that is malformed, not a real date, or out of range.400 AMBIGUOUS_TARGET— more than one reference form, orcompare_unix/compare_unix_ms/compare_isocombined with a target selector ("Provide either compare_unix/compare_unix_ms/compare_iso or a compare target selector, but not both.").400 INVALID_PARAMETER— a country with no holiday calendar ("Unsupported holiday calendar."), an unknownholiday_subdivision("Unknown holiday_subdivision 'XX' for country DE.";FI-1must be writtenFI-01), a malformed code, or a business-day range outside 1900–2100 with a calendar ("Holiday calendar coverage is only available for years 1900-2100."). The 249 countries and their subdivision codes: Holiday calendars.
When to use this endpoint
Use Elapsed since to show how much time has passed since a timestamp or how much time is left until a future timestamp. It is a compact fit for status pages, billing windows, event countdowns, and audit interfaces.
Request model
Provide exactly one reference timestamp as unix, unix_ms, or iso. The endpoint compares that reference against the current request time, or against an optional compare_unix / compare_unix_ms / compare_iso timestamp, and returns duration fields plus a human-readable string.
Direction semantics
The direction field tells you whether the reference is already passed or still left (equal instants count as passed). Use that value to label UI states without reimplementing comparison logic in the browser.
Frequently asked questions
How do I build a countdown with an API?
Call GET /v1/time/elapsed?iso=2026-01-01T00:00:00Z. direction is passed once the reference is behind you and left while it is still ahead, so the same call works as a countdown before the date and a timer after it.
Can I compare two timestamps instead of now?
Yes. Add compare_iso, compare_unix or compare_unix_ms to measure between the reference and that timestamp.
Are the seconds, minutes, hours and days fields a breakdown?
No. Each is the whole duration in that unit, so 1 day is 86400 seconds, 1440 minutes, 24 hours and 1 day.