Timestamps
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.
| Timestamp | Description |
|---|---|
metadata.addedAt | The date and time when the record was ingested into Terminal |
metadata.modifiedAt | The date and time when the record was last updated in Terminal |
metadata.deletedAt | The date and time when the record was deleted from Terminal. When Terminal no longer sees the record in the source system, this timestamp is set to indicate a soft delete. By default, Terminal will not return deleted records in the response |
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.
| Timestamp | Description |
|---|---|
createdAt | The date and time when the record was created in the source system when available |
updatedAt | The date and time when the record was last updated in the source system when available |
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:
- Chronology: Understanding when events occurred in the real world
- Filtering: Filtering records by when events happened
- Partitioning: Efficiently storing and retrieving data based on time periods
- 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:
| Common Model | Timestamp | Format | Description |
|---|---|---|---|
| Safety Event | startedAt | ISO 8601 | The date and time when the safety event started |
| Vehicle Stat Log | timestamp | ISO 8601 | The date and time when the vehicle statistics were recorded |
| Vehicle Location | locatedAt | ISO 8601 | The date and time when the vehicle was at the recorded location |
| Latest Vehicle Location | locatedAt | ISO 8601 | The date and time when the vehicle was at the recorded location |
| Latest Trailer Location | locatedAt | ISO 8601 | The date and time when the trailer was at the recorded location |
| Trip | startedAt | ISO 8601 | The date and time when the trip began |
| HOS Log | startedAt | ISO 8601 | The date and time when the HOS status period began |
| HOS Daily Log | date | YYYY-MM-DD | The calendar date of the daily log |
| IFTA Summary | month | YYYY-MM | The month and year of the IFTA report |
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.
| Access Pattern | Use Case |
|---|---|
| Modified Time | Ideal for syncing data to capture all changes effectively |
| Record Time | Best for analyzing when events occurred in the real world |
| Combined Approach | Targets records within a range that have been changed since a specific date |
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
modifiedAfterandmodifiedBeforeto easily sync only the data that has changed. - For user interfaces: Consider using record-specific filters like
startedAfterandstartedBeforeto 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.