Skip to main content

​
Overview

This guide explains the different timestamps that are available for records in Terminal. Unless otherwise specified, the timestamps are in UTC, and are represented in ISO 8601 format.

​
Available Timestamps

​
Terminal Metadata

Terminal system timestamps are included in the metadata object that is returned with each record. These timestamps are related to when Terminal processes the data, rather than when events occur in the source system.
For details on the available timestamps for each model, see the model reference.

​
Source Metadata

The source system may include timestamps indicating when a record was created or updated. These timestamps are top-level properties on records and may not be available for all providers. They are primarily associated with core entities such as Vehicle, Driver, and Device. Other models representing events or logs will have more specific timestamps.
For details on the available timestamps for each model, see the model reference.

​
Record Time

Given many of Terminal’s models represent events or logs, many of these records will also include additional timestamps that are specific to the record type. These fields are critical for:
  1. Chronology: Understanding when events occurred in the real world
  2. Filtering: Filtering records by when events happened
  3. Partitioning: Efficiently storing and retrieving data based on time periods
  4. Time-Series Analysis: Analyzing patterns over time based on when events actually occurred
The table below summarizes the primary record-specific timestamp for each type of record:
For details on all fields, including other timestamps for each model, refer to the model reference.
Note that these timestamps are distinct from Terminal’s system timestamps (metadata.addedAt, metadata.modifiedAt). While Terminal system timestamps track when data was processed by Terminal, these record-specific timestamps represent when events actually occurred according to the source system.

​
Filtering by Time

Given we now have an understanding of the different types of timestamps available, let’s take a look at the different ways to filter records by time across Terminal’s APIs. Choosing the right access pattern is important to ensure that your data is filtered correctly and efficiently. If you have any questions or would like some help figuring out the best access pattern for your situation, please don’t hesitate to reach out to our support team. Here are some helpful scenarios to think about for each approach:
  • For ETL and data pipelines: You can use modifiedAfter and modifiedBefore to easily sync only the data that has changed.
  • For user interfaces: Consider using record-specific filters like startedAfter and startedBefore to show data based on when events actually happened.
  • For partitioned ETL pipelines: You might find it useful to combine both types of filters to find recently updated historical records for each partition.
For a comprehensive list of all available filters, refer to the API reference.

​
Modified Time

Various endpoints support filtering by modifiedAt timestamp using the modifiedAfter and modifiedBefore query parameters. These filters apply to the metadata.modifiedAt field. For example, to retrieve safety events that were modified in Terminal between January 1, 2023 and January 31, 2023:
This request would return safety events whose metadata.modifiedAt timestamp falls within the specified time range:
You can also use only one of the parameters. For example, to retrieve all safety events modified after a specific date:
Or to retrieve all safety events modified before a specific date:
These filters are particularly useful for syncing data with your systems, allowing you to fetch only records that have changed since your last sync.

​
Record Time

In addition to filtering by when records were modified in Terminal, many endpoints support filtering by the record’s own timestamp. For example, you can filter safety events by when they actually occurred using the startedAfter and startedBefore parameters. To retrieve safety events that occurred between January 15, 2023 and January 16, 2023:
This request would return safety events whose startedAt timestamp falls within the specified time range:
As with the metadata filters, you can also use only one of the parameters. For example, to retrieve all safety events that occurred after a specific date:
These filters are more useful for analytical purposes when you’re interested in events that occurred during a specific time period, regardless of when they were ingested or updated in Terminal.