Dates & Times

REST request and response fields that hold a date or a moment in time are declared in the OpenAPI specs as date or date-time, and the reference pages show that format next to the field. Some timestamp fields, such as updated-at on orders and expires-at on quote alerts, declare no format at all and show as a plain string. For those, rely on the example and the description. A few fields are not strings at all: see Epoch values.

Two formats

In the specs, updated-at and expires-at are declared date-time on some schemas and carry no format on others, so the table lists the fields that use each form, not a guarantee for every schema.

A plain date names a day and carries no time or offset. A date-time names an exact moment.

Parse the offset, don't match the text

The published examples show a UTC moment written two ways: with a trailing Z (2024-01-15T14:30:00.000Z) and with an explicit offset (2024-07-31T16:50:23.417+00:00). Both mean the same thing. Parse timestamps with an ISO 8601 parser that understands offsets, and compare the parsed values. Comparing the raw strings, or hashing them, will treat two equal moments as different.

Fractional seconds can also vary in length, so don't assume a fixed number of digits.

Date or date-time in a query

Several endpoints that filter by time accept both forms as separate parameters, for example start-date / end-date and start-at / end-at on transactions and orders.

• Use the -date pair to bound a query to whole days.
• Use the -at pair when you need a specific moment inside a day.

Check the reference page for the endpoint you're calling. See Pagination & Filtering for the filters the transactions endpoint supports.

Market hours

Session times such as open-at and close-at come back as date-times. The regular equity open is 9:30 a.m. in New York, which is 13:30 UTC during daylight saving time and 14:30 UTC otherwise, so a fixed offset will be wrong for part of the year. Read session times from the Market Sessions endpoints instead of hard-coding them.

Epoch values

Not every time value is an ISO 8601 string. In the Market Data reference, haltStartTime, haltEndTime and lastTradeTime are epoch timestamps, and the two halt fields are -1 when the security is not halted. In the streaming API, the timestamp on a notification is epoch milliseconds, and the fromTime on a Candle subscription is epoch seconds. The DXLink Profile event's haltStartTime and haltEndTime are epoch milliseconds too, according to dxFeed's event documentation. Check each field's description for its unit before parsing it as a date.