--- title: "Gets the number of devices and shipments in each event state" method: GET path: "/events/v3/statuses/deviceCounts" tags: ["Events"] --- # Gets the number of devices and shipments in each event state `GET /events/v3/statuses/deviceCounts` This API call counts the number of devices and shipments that are currently in the different event states per rule or per event source (that is per rule type). An event state of a device is the event type of the most recent device event. It indicates a state the device is currently in, in relation to a rule the device is associated with. For example, the event state can be either `INSIDE_GEOFENCE` or `OUTSIDE_GEOFENCE` in case the event source is `geofence`; or `BELOW_RANGE`, `IN_RANGE` or `ABOVE_RANGE` in case the event source is `battery` rule. A device can be in several different event states at the same time when it has more than one rule associated with it. For example, a device can be at the same time in `INSIDE_GEOFENCE` and `ABOVE_RANGE` event states. The same applies for shipments. The `groupBy` query parameter defines how the results are grouped. The default value for the `groupBy` parameter is `ruleId`. The response contains a list of objects, one per each rule, that are associated to at least one device or shipment of the project. Each object has the following properties: * `ruleId`: a rule ID * `eventSource`: the rule type * every distinct event state (applicable for the rule type) and the number of devices in this state * `total`: the total number of devices associated to the rule When the `groupBy` parameter value is `eventSource`, the response contains a list of objects, one per event source (that is per each rule type), that are associated to at least one device or shipment of the project. Each object has the following properties: * `eventSource`: a rule type * every distinct event state (applicable for the rule type) and the number of devices in this state. One device is counted only once per `eventType` state, but in case a single device is associated to multiple rules of the same type, it will be counted separately for each event state. * `total`: the total number of devices associated to the rule type. A single device is counted only once. For example, a device A is associated to 2 geofences and is inside one and outside the other. A device B is associated to 3 geofences and is outside all of them. With the request query parameter set as `groupBy`=`eventSource`, the response body will contain the following result item: ``` { "eventSource": "geofence", "INSIDE_GEOFENCE": 1, "OUTSIDE_GEOFENCE": 2, "total": 2 }. ``` If the request is supplied with `eventSource` query parameter, the response results will be limited to the specified rule types only. If the request is supplied with `ruleId` query parameter, the response results will be limited to the specified rule IDs only. If the request is supplied with `trackingId` query parameter, the response results will be limited to the specified devices only. Also `shipmentId` can be used as a `trackingId`. If the request is supplied with `geofenceId` query parameter, it will only affect dwelling event statuses filtering, limiting the results to the specified geofence only. Other event types are not affected by this setting. Note that for the event statuses of geofence type, the `ruleId` is the `geofenceId`. If the request is supplied with `shipments` query parameter, the response results will be limited either to shipments (`shipments`=`true`) or devices (`shipments`=`false`) only. Otherwise, if `shipments` query parameter is not specified, response results will include both devices and shipments. All the aforementioned query parameters can be combined together. ## Query parameters - `groupBy` 'ruleId' | 'eventSource' — Define whether the number of devices and shipments in each event state is calculated per rule ID or per rule type. - `eventSource` union - 'attach' | 'battery' | 'geofence' | 'humidity' | 'pressure' | 'tamper' | 'temperature' | 'acceleration' | 'dwelling' | 'detention' | 'utilization' | 'online' | 'shipmentSchedule' — Source of the event. - string[] - `trackingId` union - string — 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. - string[] - `ruleId` union - string, uuid — ID of the rule or geofence. Must be a valid UUIDv4. - string[] - `geofenceId` union - string, uuid — ID of the geofence. Must be a valid UUIDv4. This filter can be used to filter results related to dwelling event source. - string[] - `shipments` boolean — If `true`, the results will be limited to shipment event statuses only. If `false`, the results will be limited to device event statuses only. If not specified, the results will include both device and shipments event statuses. - `pageToken` string - `count` integer - `appId` string ## Response `200` Successful - 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 - `FALSE_TO_TRUE` number, required — Number of devices currently in this event state. - `TRUE_TO_FALSE` number, required — Number of devices currently in this event state. - `eventSource` 'attach' | 'tamper' | 'online', required - `ruleId` string, uuid — Must be a valid UUIDv4. - `total` number, required — Number of devices associated to the respective rule or rules. - object - `ABOVE_RANGE` number, required — Number of devices currently in this event state. - `BELOW_RANGE` number, required — Number of devices currently in this event state. - `IN_RANGE` number, required — Number of devices currently in this event state. - `eventSource` 'battery' | 'humidity' | 'pressure' | 'temperature', required - `ruleId` string, uuid — Must be a valid UUIDv4. - `total` number, required — Number of devices associated to the respective rule or rules. - object - `EVENT` number, required — Number of devices currently in this event state. - `eventSource` 'acceleration', required - `ruleId` string, uuid — Must be a valid UUIDv4. - `total` number, required — Number of devices associated to the respective rule or rules. - object - `INSIDE_GEOFENCE` number, required — Number of devices currently in this event state. - `OUTSIDE_GEOFENCE` number, required — Number of devices currently in this event state. - `eventSource` 'geofence', required - `ruleId` string, uuid — Must be a valid UUIDv4. - `total` number, required — Number of devices associated to the respective rule or rules. - object - `DWELLING_ENDED` number, required — Number of devices currently in this event state. - `DWELLING_STARTED` number, required — Number of devices currently in this event state. - `eventSource` 'dwelling', required - `ruleId` string, uuid — Must be a valid UUIDv4. - `total` number, required — Number of devices associated to the respective rule or rules. - object - `DETENTION_ENDED` number, required — Number of devices currently in this event state. - `DETENTION_STARTED` number, required — Number of devices currently in this event state. - `eventSource` 'detention', required - `ruleId` string, uuid — Must be a valid UUIDv4. - `total` number, required — Number of devices associated to the respective rule or rules. - object - `UNUTILIZED` number, required — Number of devices currently in this event state. - `UTILIZED` number, required — Number of devices currently in this event state. - `eventSource` 'utilization', required - `ruleId` string, uuid — Must be a valid UUIDv4. - `total` number, required — Number of devices associated to the respective rule or rules. - object - `SHIPMENT_DELAYED` number, required — Number of devices currently in this event state. - `SHIPMENT_EARLY` number, required — Number of devices currently in this event state. - `SHIPMENT_ON_TIME` number, required — Number of devices currently in this event state. - `eventSource` 'shipmentSchedule', required - `ruleId` string, uuid — Must be a valid UUIDv4. - `total` number, required — Number of devices associated to the respective rule or rules. ## 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)