Skip to content
Endpoint guide

Elapsed since

GET /v1/time/elapsedOpenAPI YAML

Time between a reference timestamp and now (or a compare timestamp), with direction (passed or left).

What do I need to send?

Required / choose this first

Provide exactly one reference timestamp: unix, unix_ms, or iso.

Optional

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.

NameNeeded?Use it for
unixChoose one inputReference timestamp as Unix seconds.
unix_msChoose one inputReference timestamp as Unix milliseconds.
isoChoose one inputReference timestamp as ISO 8601.
source_tzConditional hintInterpret a local iso= reference as wall time in this IANA zone.
source_ipConditional hintInterpret a local iso= reference using this IP address timezone.
source_latPair parameterLatitude hint for local iso=. Pair with source_lon.
source_lonPair parameterLongitude hint for local iso=. Pair with source_lat.
source_offsetConditional hintInterpret a local iso= reference against a fixed UTC offset.
compare_unixChoose one inputOptional comparison timestamp as Unix seconds instead of now.
compare_unix_msChoose one inputOptional comparison timestamp as Unix milliseconds instead of now.
compare_isoChoose one inputOptional comparison timestamp as ISO 8601 instead of now.
compare_source_tzConditional hintInterpret a local compare_iso= timestamp as wall time in this IANA zone.
compare_source_ipConditional hintInterpret a local compare_iso= timestamp using this IP address timezone.
compare_source_latPair parameterLatitude hint for local compare_iso=. Pair with compare_source_lon.
compare_source_lonPair parameterLongitude hint for local compare_iso=. Pair with compare_source_lat.
compare_source_offsetConditional hintInterpret a local compare_iso= timestamp against a fixed UTC offset.
tzChoose one targetAccepted for symmetry: "now" is the same instant in every zone, so this does not change the result. Cannot be combined with compare_*.
ipChoose one targetAccepted for symmetry; does not change the result. Cannot be combined with compare_*.
latPair parameterAccepted for symmetry with lon; does not change the result.
lonPair parameterAccepted for symmetry with lat; does not change the result.
offsetChoose one targetAccepted for symmetry; does not change the result. Cannot be combined with compare_*.
auto_tzChoose one targetAccepted for symmetry; does not change the result.
formatOptionalDuration template using %days %hours %minutes %seconds for an additional `formatted` field.
business_daysOptionalSet true (or 1 / yes) to include a business_days count in the response. Counted by calendar date, start included, end excluded.
holiday_countryConditionalHoliday 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_subdivisionConditionalSubdivision 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.
signOptionalSet 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, or compare_unix/compare_unix_ms/compare_iso combined 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 unknown holiday_subdivision ("Unknown holiday_subdivision 'XX' for country DE."; FI-1 must be written FI-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.