​
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.
TimestampDescription
metadata.addedAtThe date and time when the record was ingested into Terminal
metadata.modifiedAtThe date and time when the record was last updated in Terminal
metadata.deletedAtThe 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.
TimestampDescription
createdAtThe date and time when the record was created in the source system when available
updatedAtThe 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:
  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:
Common ModelTimestampFormatDescription
Safety EventstartedAtISO 8601The date and time when the safety event started
Vehicle Stat LogtimestampISO 8601The date and time when the vehicle statistics were recorded
Vehicle LocationlocatedAtISO 8601The date and time when the vehicle was at the recorded location
Latest Vehicle LocationlocatedAtISO 8601The date and time when the vehicle was at the recorded location
Latest Trailer LocationlocatedAtISO 8601The date and time when the trailer was at the recorded location
TripstartedAtISO 8601The date and time when the trip began
HOS LogstartedAtISO 8601The date and time when the HOS status period began
HOS Daily LogdateYYYY-MM-DDThe calendar date of the daily log
IFTA SummarymonthYYYY-MMThe 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 PatternUse Case
Modified TimeIdeal for syncing data to capture all changes effectively
Record TimeBest for analyzing when events occurred in the real world
Combined ApproachTargets 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 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: 
curl -X GET "https://api.withterminal.com/tsp/v1/safety/events?modifiedAfter=2023-01-01T00:00:00Z&modifiedBefore=2023-01-31T23:59:59Z" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Connection-Token: YOUR_CONNECTION_TOKEN"
This request would return safety events whose metadata.modifiedAt timestamp falls within the specified time range: 
{
  "results": [
    {
      "id": "sft_evt_01HG3R5T7XYZABC123",
      "sourceId": "event-12345",
      "provider": "geotab",
      "type": "speeding",
      "startedAt": "2023-01-15T14:23:47Z",
      "endedAt": "2023-01-15T14:23:52Z",
      "driver": "drv_01HF2P4Q5KLMNO678",
      "vehicle": "vcl_01HF3V9W2QRSTU901",
      "metadata": {
        "addedAt": "2023-01-15T15:01:23Z",
        "modifiedAt": "2023-01-15T15:01:23Z"
      }
    }
    // Additional safety events...
  ],
  "next": "ABC123XYZ"
}
You can also use only one of the parameters. For example, to retrieve all safety events modified after a specific date: 
curl -X GET "https://api.withterminal.com/tsp/v1/safety/events?modifiedAfter=2023-01-15T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Connection-Token: YOUR_CONNECTION_TOKEN"
Or to retrieve all safety events modified before a specific date: 
curl -X GET "https://api.withterminal.com/tsp/v1/safety/events?modifiedBefore=2023-01-15T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Connection-Token: YOUR_CONNECTION_TOKEN"
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: 
curl -X GET "https://api.withterminal.com/tsp/v1/safety/events?startedAfter=2023-01-15T00:00:00Z&startedBefore=2023-01-16T23:59:59Z" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Connection-Token: YOUR_CONNECTION_TOKEN"
This request would return safety events whose startedAt timestamp falls within the specified time range: 
{
  "results": [
    {
      "id": "sft_evt_01HG3R5T7XYZABC123",
      "sourceId": "event-12345",
      "provider": "geotab",
      "type": "speeding",
      "startedAt": "2023-01-15T14:23:47Z",
      "endedAt": "2023-01-15T14:23:52Z",
      "driver": "drv_01HF2P4Q5KLMNO678",
      "vehicle": "vcl_01HF3V9W2QRSTU901",
      "metadata": {
        "addedAt": "2023-01-15T15:01:23Z",
        "modifiedAt": "2023-01-15T15:01:23Z"
      }
    }
    // Additional safety events...
  ],
  "next": "ABC123XYZ"
}
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: 
curl -X GET "https://api.withterminal.com/tsp/v1/safety/events?startedAfter=2023-01-15T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Connection-Token: YOUR_CONNECTION_TOKEN"
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.