Date and time handling in the Data Export API

The date and time model

Three rules describe how the API handles dates and times:

1. Every request to /jobs and /printer-states must include a timezone parameter that contains a valid IANA timezone identifier, for example America/Denver or Europe/Bucharest.
2. Any startDateTime or endDateTime value supplied in the request is interpreted as a local time in the supplied timezone. The values do not include a UTC offset.
3. Every date and time value in the response is formatted as a local time in the same timezone, using the pattern YYYY-MM-DDTHH:MM:SS.sss.

The timezone parameter governs the meaning of the request and the formatting of the response. Two requests for the same underlying data, submitted with different timezones, produce responses with different timestamp strings even though they describe the same events.

Date and time format

The API uses one format for all date and time values, in both requests and responses:

YYYY-MM-DDTHH:MM:SS.sss

For example, 2026-03-15T14:30:00.000 is 2:30:00 PM on March 15, 2026, interpreted in the timezone supplied with the request.

In requests, the milliseconds portion (.sss) is optional. In responses, it is always present.

Default time range

You can omit startDateTime, endDateTime, or both. The two defaults are applied independently:

• If you omit startDateTime, the API uses 24 hours before the current time as the start of the range.
• If you omit endDateTime, the API uses the current time as the end of the range.

The defaults combine in the way you would expect:

• If you omit both values, the API returns data for the previous 24 hours.
• If you supply startDateTime as one hour ago and omit endDateTime, the API returns data for the previous hour.
• If you supply endDateTime and omit startDateTime, the API returns data for the range starting 24 hours before the request and ending at the endDateTime.

Default values are calculated in the timezone supplied with the request.

Data retention: the previous seven days

The Data Export API serves real-time operational data. Job records and printer state history are available for the previous seven days only. A request for data older than seven days returns an error.

Plan your integration so that scheduled extracts run frequently enough to capture all data before it ages out:

• For nightly extracts, allow a margin of at least one or two days. If a scheduled run fails, you have time to investigate and re-run before the data is no longer available.
• For backfills or one-time extracts, do not request data more than seven days old.

Rules for the requested range

• startDateTime must be earlier than endDateTime. A request that violates this rule fails with ERR_INVALID_DATE_RANGE.
• Both values must use the format described in Date and time format. A request with a malformed value fails with ERR_INVALID_DATE_FORMAT.
• The duration between startDateTime and endDateTime must not exceed the maximum allowed range. A request that exceeds the maximum fails with ERR_DATE_RANGE_EXCEEDED.

Supplying the timezone

The timezone parameter accepts IANA timezone identifiers, such as America/Denver, America/New_York, Europe/Bucharest, Asia/Tokyo, or UTC. The interactive documentation page lists every value that the API accepts.

An invalid or unrecognized identifier fails with ERR_INVALID_TIMEZONE. Three-letter abbreviations such as MST or EST are not IANA identifiers and are not accepted; use the corresponding region-based identifier (for example, America/Denver or America/New_York) instead.

Daylight saving time and ambiguous times

Because requests and responses are expressed as local times, daylight saving time transitions create two situations to be aware of:

Skipped local times in the spring transition

When clocks move forward, one hour of local time does not exist. For example, in America/Denver on the day of the spring transition, 02:30:00 is not a valid local time. Avoid using times in the skipped hour as startDateTime or endDateTime.

Repeated local times in the fall transition

When clocks move back, one hour of local time occurs twice. A value such as 01:30:00 on the day of the fall transition is ambiguous. Choose times outside the repeated hour to avoid uncertainty about which instance you are requesting.

If your integration runs unattended and might submit a request whose start or end time falls inside a transition, schedule the request to run a few hours away from the transition or use times that are clearly outside it.

Recommendations for storing and comparing response timestamps

Response timestamps are local times without an offset. To avoid ambiguity in downstream systems, consider one of the following approaches:

• Store the response timestamp together with the timezone you supplied in the request. The pair, taken together, identifies a unique instant in time.
• In your integration, convert each response timestamp to UTC before storing it, using the timezone you supplied in the request. Storing UTC values simplifies comparisons across data extracted with different timezones.
• Always submit requests with the same timezone, for example UTC, so that all stored timestamps are directly comparable.

Examples

The following examples illustrate how the timezone, start time, and end time work together.

Default window in Mountain Time

A request submitted at 9:00 AM on March 15, 2026, in America/Denver, with no start or end time supplied, returns data from 2026-03-14T09:00:00 through 2026-03-15T09:00:00, both interpreted in Mountain Time.

Specific window in Eastern European Time

A request that supplies timezone=Europe/Bucharest, startDateTime=2026-03-15T08:00:00, and endDateTime=2026-03-15T16:00:00 returns data for the eight-hour business day in Bucharest local time. Response timestamps are also formatted in Bucharest local time.

The same window viewed in two timezones

To retrieve the same underlying data twice, formatted for two audiences, submit two requests with different timezone values and adjust startDateTime and endDateTime so that they describe the same instants in each timezone. The response payloads describe the same events but use different timestamp strings.