Skip to content
Sign inGet started

Date and time

The date and time service answers the date questions an agent most often gets wrong when it works them out itself: what time it is now, and where; what date lies a given number of days, months or years from another; how long lies between two dates; how to write a date in a given format; and which name a time zone goes by. It can also pause for a short, bounded time.

It offers a trial, and it can also be enabled in full and billed per use.

Every one of its tools only reads: none changes anything of your account's, and none reaches outside this system.

Its tools

  • datetime_now gives the current time in UTC, and in any IANA time zones you name in timeZones. Each zone comes back with its local time, its offset from UTC, its short name and whether daylight saving is in effect. Each call is charged one unit (datetime-now).
  • datetime_calculate adds or subtracts amounts of time to a date. One call holds several independent calculations, each starting from the same date and each an ordered list of steps — an amount and a unit — applied one after another, so "one month on, then one day back" is one calculation. Give a calculation a label to find its result by. Each call is charged one unit per calculation it holds (datetime-calculate).
  • datetime_difference measures the span between from and to: a breakdown in the units you ask for (days, hours, minutes and seconds unless you say otherwise) and the exact totals. The span is never given as negative, and negative says whether to is before from. Each call is charged one unit (datetime-difference).
  • datetime_format writes a date in one format: ISO 8601 in full or as the date or time alone, RFC 2822, the HTTP date form, Unix seconds or milliseconds, your own token pattern, a locale's own conventions at a style from short to full, or relative text such as "in 3 days", measured from relativeTo or from now. Each call is charged one unit (datetime-format).
  • datetime_timezones finds time-zone names by any part of the name, with spaces read as underscores, so new york finds America/New_York. Each zone comes back with its current offset and short name. With no query it lists every zone, up to limit. Each call is charged one unit (datetime-timezones).
  • datetime_wait pauses for milliseconds, then says when the wait started and ended. Each call is charged one unit whatever its length (datetime-wait).

Its limits

Dates are ISO 8601 and begin with the year: 2026-09-27, 2026-09-27T14:30, 2026-09-27T14:30:00+10:00, 2026-09-27T04:30:00Z, a week date such as 2026-W39-7 or an ordinal date such as 2026-270. A time on its own, with no date, is not accepted, and neither is free text such as "next Tuesday". A date with no offset is read in the call's timeZone, which is UTC unless you name another; a date with an offset is that exact instant, and timeZone then only chooses the zone the answer is written in.

A time zone is an IANA name, such as Australia/Sydney, Europe/London or UTC. A bare offset such as +05:30 is not a time zone: put it in the date instead.

Calendar units follow the calendar. Days, weeks, months, quarters and years are counted in the call's zone, so a day across a daylight-saving change keeps the local time and may be 23 or 25 hours long, and a month that lands past the end of a shorter month stops at its last day: 31 January plus one month is 28 February, or 29 in a leap year. Milliseconds, seconds, minutes and hours are exact elapsed time.

Patterns use tokens. yyyy is the year, MM the month number, MMMM the month's name, dd the day, EEEE the weekday's name, HH the hour on a 24-hour clock, mm the minute, ss the second and ZZ the offset. Literal text goes in single quotes — EEEE d MMMM yyyy 'at' HH:mm — and a token that is not recognised is written out as it stands rather than refused.

A wait is at most 30 seconds. An AI client gives up on a call that takes too long — commonly after about a minute — and this server cannot keep a call alive past that point, so a longer wait would be charged and its answer never arrive.

Time-zone data is the server runtime's own. The zone names and their rules — when daylight saving starts and ends, and what each offset is — come from the runtime this server runs on, so a zone rule a government changes arrives with the next runtime upgrade. datetime_timezones lists what that runtime lists, plus UTC; some other spellings, such as Etc/UTC, are still accepted wherever a time zone is asked for.