---
title: "Gets event history"
method: GET
path: "/events/v3"
tags: ["Events"]
---

# Gets event history

`GET /events/v3`

Gets all events for all devices and shipments of the project. The results are listed in descending order 
based on the timestamp. 

An event is uniquely identified by `trackingId`-`ruleId`-`timestamp` key, 
with an exception of dwelling and stock rule events. 
Dwelling events also need `geofenceId` to be specified, 
whereas for stock events `trackingId` is not applicable.

A time range can be defined with `before` and `after` timestamps. The response will contain
an array of events that were recorded within the range.

If the request is supplied with `eventSource` query parameter, the response will contain
events generated by the defined source only.

If the request is supplied with `eventType` query parameter, the response will contain
events of the specified type only.

If the request is supplied with `ruleId` query parameter, the response will only contain events
for the specified rule ID.

If the request is supplied with `initialState` query parameter, the response will contain
events having the specified initial state.

All the aforementioned query parameters can be combined together.

## Query parameters

- `before` number
- `after` number
- `eventSource` union
  - 'attach' | 'battery' | 'geofence' | 'humidity' | 'pressure' | 'tamper' | 'temperature' | 'acceleration' | 'dwelling' | 'stock' | 'detention' | 'utilization' | 'online' | 'shipmentSchedule' — The event source rule type.
  - string[]
- `eventType` union
  - 'BELOW_RANGE' | 'IN_RANGE' | 'ABOVE_RANGE' | 'FALSE_TO_TRUE' | 'TRUE_TO_FALSE' | 'EVENT' | 'INSIDE_GEOFENCE' | 'OUTSIDE_GEOFENCE' | 'OVERSTOCK' | 'NORMAL_VOLUME' | 'UNDERSTOCK' | 'DWELLING_STARTED' | 'DWELLING_ENDED' | 'DETENTION_STARTED' | 'DETENTION_ENDED' | 'UTILIZED' | 'UNUTILIZED' | 'SHIPMENT_EARLY' | 'SHIPMENT_ON_TIME' | 'SHIPMENT_DELAYED' — Type of the event. An event is created every time an associated rule or geofence is triggered by a device ingestion. The event type depends on the data the device sends. Sensors that report numerical data (such as battery, humidity, pressure and temperature sensors), generate an event when the reported sensor reading of the device goes in or out of range, which is configured in the rule. This produces events of BELOW_RANGE, IN_RANGE and ABOVE_RANGE types. Sensors that report boolean data (such as attach and tamper sensors), generate events when the device transitions from one state to another, either from `false` to `true` or vice versa. This produces events of FALSE_TO_TRUE and TRUE_TO_FALSE types. The same event types are also generated by the online rule when the device state changes from `offline` (when the device has stopped ingesting data) to `online` (when the device data ingestion has resumed) or vice versa. The acceleration sensor generates events whenever the reported sensor reading crosses the acceleration threshold (for example, when the device was dropped). This produces events of the type EVENT. Such events are stateless. Events of INSIDE_GEOFENCE and OUTSIDE_GEOFENCE types are generated when the device enters or exits a geofence associated with the device. Events of DWELLING_STARTED type are generated when the device has stayed inside an associated geofence for longer than the threshold duration. DWELLING_ENDED type events are generated when dwelling of the device has ended. Events of DETENTION_STARTED type are generated when the device has been stationary for longer than the threshold duration, regardless whether the device is inside or outside of any geofence. DETENTION_ENDED type events will be generated when the device starts moving again. Events of UNUTILIZED type are generated when the device has been stationary for longer than the threshold duration. UTILIZED type events are generated when the device starts moving again after having been stationary. Events of OVERSTOCK, NORMAL_VOLUME and UNDERSTOCK types are generated when the number of assets inside a geofence crosses the `minVolume` and `maxVolume` thresholds of an associated stock rule. Events of SHIPMENT_EARLY, SHIPMENT_ON_TIME and SHIPMENT_DELAYED types are generated when a shipment is too early, on time or delayed.
  - string[]
- `ruleId` union
  - string, uuid — ID of the rule or geofence. Must be a valid UUIDv4.
  - string[]
- `initialState` boolean — Events with the `initialState` property set as `true` are generated when the rule is evaluated for the first time. It indicates the fact that this is the initial evaluation state, which would serve as a starting point for the subsequent rule evaluations. The rest of the rule events would represent a transition of a device or a shipment or a geofence from one state to another and their `initialState` property will be set to `false`.
- `pageToken` string
- `count` integer
- `appId` string

## Response `200`

Successful

The events were successfully retrieved.

- object
  - `count` integer — The number of items in the response.
  - `pageToken` string — A token that can be used to retrieve the next page of the response.
  - `data` union[]
    - union
      - object — Events generated by online rule or by sensors that report boolean data (attach, tamper).
        - `initialState` boolean, required — Events with the `initialState` property set as `true` are generated when the rule is evaluated for the first time. It indicates the fact that this is the initial evaluation state, which would serve as a starting point for the subsequent rule evaluations. The rest of the rule events would represent a transition of a device or a shipment or a geofence from one state to another and their `initialState` property will be set to `false`.
        - `ruleId` string, uuid, required — Must be a valid UUIDv4.
        - `timestamp` integer, required — Milliseconds elapsed since 1 January 1970 00:00:00 UTC.
        - `trackingId` string, required — This is a unique ID associated with the device data in HERE Tracking. For physical devices the `trackingId` gets assigned to a device when the device is claimed by a user, and for virtual devices it is an external device ID along with the device project `appId`. Alternatively, a valid `shipmentId` may be used.
        - `eventSource` 'attach' | 'tamper' | 'online', required — The event source rule type.
        - `eventType` 'FALSE_TO_TRUE' | 'TRUE_TO_FALSE', required
      - object — Events generated by sensor that report numerical data (battery, humidity, pressure and temperature).
        - `initialState` boolean, required — Events with the `initialState` property set as `true` are generated when the rule is evaluated for the first time. It indicates the fact that this is the initial evaluation state, which would serve as a starting point for the subsequent rule evaluations. The rest of the rule events would represent a transition of a device or a shipment or a geofence from one state to another and their `initialState` property will be set to `false`.
        - `ruleId` string, uuid, required — Must be a valid UUIDv4.
        - `timestamp` integer, required — Milliseconds elapsed since 1 January 1970 00:00:00 UTC.
        - `trackingId` string, required — This is a unique ID associated with the device data in HERE Tracking. For physical devices the `trackingId` gets assigned to a device when the device is claimed by a user, and for virtual devices it is an external device ID along with the device project `appId`. Alternatively, a valid `shipmentId` may be used.
        - `eventSource` 'battery' | 'humidity' | 'pressure' | 'temperature', required — The event source rule type.
        - `eventType` 'BELOW_RANGE' | 'IN_RANGE' | 'ABOVE_RANGE', required
      - object — Events generated by sensor that report numerical data but only when a specific event occurs (eg. the device was dropped)
        - `initialState` boolean, required — Events with the `initialState` property set as `true` are generated when the rule is evaluated for the first time. It indicates the fact that this is the initial evaluation state, which would serve as a starting point for the subsequent rule evaluations. The rest of the rule events would represent a transition of a device or a shipment or a geofence from one state to another and their `initialState` property will be set to `false`.
        - `ruleId` string, uuid, required — Must be a valid UUIDv4.
        - `timestamp` integer, required — Milliseconds elapsed since 1 January 1970 00:00:00 UTC.
        - `trackingId` string, required — This is a unique ID associated with the device data in HERE Tracking. For physical devices the `trackingId` gets assigned to a device when the device is claimed by a user, and for virtual devices it is an external device ID along with the device project `appId`. Alternatively, a valid `shipmentId` may be used.
        - `eventSource` 'acceleration', required — The event source: acceleration rule
        - `eventType` 'EVENT', required
      - object — Events generated by device crossing the geofence border.
        - `initialState` boolean, required — Events with the `initialState` property set as `true` are generated when the rule is evaluated for the first time. It indicates the fact that this is the initial evaluation state, which would serve as a starting point for the subsequent rule evaluations. The rest of the rule events would represent a transition of a device or a shipment or a geofence from one state to another and their `initialState` property will be set to `false`.
        - `ruleId` string, uuid, required — Must be a valid UUIDv4.
        - `timestamp` integer, required — Milliseconds elapsed since 1 January 1970 00:00:00 UTC.
        - `trackingId` string, required — This is a unique ID associated with the device data in HERE Tracking. For physical devices the `trackingId` gets assigned to a device when the device is claimed by a user, and for virtual devices it is an external device ID along with the device project `appId`. Alternatively, a valid `shipmentId` may be used.
        - `eventSource` 'geofence', required — The event source: geofence rule
        - `eventType` 'INSIDE_GEOFENCE' | 'OUTSIDE_GEOFENCE', required
      - object — Events generated by the number of assets inside a geofence over a maximum stock volume, or between a minimum stock volume and a maximum stock volume, or under a minimum stock volume.
        - `eventSource` 'stock', required — The event source: stock rule
        - `eventType` 'OVERSTOCK' | 'NORMAL_VOLUME' | 'UNDERSTOCK', required — The "OVERSTOCK" type - Events are triggered when the number of assets is over a maximum stock volume. The "UNDERSTOCK" type - Events are triggered when the number of assets is under a minimum stock volume. The "NORMAL_VOLUME" type - Events are triggered when the number of assets is between the minimum stock volume and the maximum stock volume.
        - `ruleId` string, uuid, required — Must be a valid UUIDv4.
        - `timestamp` integer, required — Milliseconds elapsed since 1 January 1970 00:00:00 UTC.
        - `initialState` boolean, required — Events with the `initialState` property set as `true` are generated when the rule is evaluated for the first time. It indicates the fact that this is the initial evaluation state, which would serve as a starting point for the subsequent rule evaluations. The rest of the rule events would represent a transition of a device or a shipment or a geofence from one state to another and their `initialState` property will be set to `false`.
      - object — Events generated by a device that has dwelled inside a geofence for longer than specified threshold duration
        - `initialState` boolean, required — Events with the `initialState` property set as `true` are generated when the rule is evaluated for the first time. It indicates the fact that this is the initial evaluation state, which would serve as a starting point for the subsequent rule evaluations. The rest of the rule events would represent a transition of a device or a shipment or a geofence from one state to another and their `initialState` property will be set to `false`.
        - `ruleId` string, uuid, required — Must be a valid UUIDv4.
        - `timestamp` integer, required — Milliseconds elapsed since 1 January 1970 00:00:00 UTC.
        - `trackingId` string, required — This is a unique ID associated with the device data in HERE Tracking. For physical devices the `trackingId` gets assigned to a device when the device is claimed by a user, and for virtual devices it is an external device ID along with the device project `appId`. Alternatively, a valid `shipmentId` may be used.
        - `eventSource` 'dwelling', required — The event source: dwelling rule
        - `eventType` 'DWELLING_STARTED' | 'DWELLING_ENDED', required
        - `geofenceId` string, uuid, required — An ID of a geofence that triggered the dwelling event
      - object — Events generated when a device has been stationary for longer than the specified threshold duration.
        - `initialState` boolean, required — Events with the `initialState` property set as `true` are generated when the rule is evaluated for the first time. It indicates the fact that this is the initial evaluation state, which would serve as a starting point for the subsequent rule evaluations. The rest of the rule events would represent a transition of a device or a shipment or a geofence from one state to another and their `initialState` property will be set to `false`.
        - `ruleId` string, uuid, required — Must be a valid UUIDv4.
        - `timestamp` integer, required — Milliseconds elapsed since 1 January 1970 00:00:00 UTC.
        - `trackingId` string, required — This is a unique ID associated with the device data in HERE Tracking. For physical devices the `trackingId` gets assigned to a device when the device is claimed by a user, and for virtual devices it is an external device ID along with the device project `appId`. Alternatively, a valid `shipmentId` may be used.
        - `eventSource` 'detention', required — The event source: detention rule
        - `eventType` 'DETENTION_STARTED' | 'DETENTION_ENDED', required
      - object — The UTILIZED event is generated when a device starts moving, and the UNUTILIZED event is generated when the device has been stationary for longer than the specified threshold duration.
        - `initialState` boolean, required — Events with the `initialState` property set as `true` are generated when the rule is evaluated for the first time. It indicates the fact that this is the initial evaluation state, which would serve as a starting point for the subsequent rule evaluations. The rest of the rule events would represent a transition of a device or a shipment or a geofence from one state to another and their `initialState` property will be set to `false`.
        - `ruleId` string, uuid, required — Must be a valid UUIDv4.
        - `timestamp` integer, required — Milliseconds elapsed since 1 January 1970 00:00:00 UTC.
        - `trackingId` string, required — This is a unique ID associated with the device data in HERE Tracking. For physical devices the `trackingId` gets assigned to a device when the device is claimed by a user, and for virtual devices it is an external device ID along with the device project `appId`. Alternatively, a valid `shipmentId` may be used.
        - `eventSource` 'utilization', required — The event source: utilization rule
        - `eventType` 'UTILIZED' | 'UNUTILIZED', required
      - object — Events generated by a shipment that is ahead or delayed from its preplanned schedule
        - `initialState` boolean, required — Events with the `initialState` property set as `true` are generated when the rule is evaluated for the first time. It indicates the fact that this is the initial evaluation state, which would serve as a starting point for the subsequent rule evaluations. The rest of the rule events would represent a transition of a device or a shipment or a geofence from one state to another and their `initialState` property will be set to `false`.
        - `ruleId` string, uuid, required — Must be a valid UUIDv4.
        - `timestamp` integer, required — Milliseconds elapsed since 1 January 1970 00:00:00 UTC.
        - `trackingId` string, required — This is a unique ID associated with the device data in HERE Tracking. For physical devices the `trackingId` gets assigned to a device when the device is claimed by a user, and for virtual devices it is an external device ID along with the device project `appId`. Alternatively, a valid `shipmentId` may be used.
        - `eventSource` 'shipmentSchedule', required
        - `eventType` 'SHIPMENT_EARLY' | 'SHIPMENT_ON_TIME' | 'SHIPMENT_DELAYED', required
        - `segmentId` string, required — An ID of the segment where the schedule deviation was detected
        - `segmentStatus` 'pending' | 'ongoing' | 'completed' | 'cancelled', required — Status of the segment.

## Other responses

- `400` — Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body.
- `401` — Unauthorized The request did not provide correct authentication details
- `403` — Forbidden The account does not have the correct privileges
- `404` — Not Found The specified resource was not found

---

[API](https://skmtc.net/here/apis/tracking.md) · [All operations](https://skmtc.net/here/apis/tracking/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/here/tracking/revisions/efa162f7023c/schema)