---
title: "Gets traces within a specified time range"
method: GET
path: "/traces/v2/{trackingId}"
tags: ["Traces"]
---

# Gets traces within a specified time range

`GET /traces/v2/{trackingId}`

Gets all traces of the device `trackingId` that were recorded within the specified time range. 
The range is defined with `before` and `after` parameters.
The returned traces are sorted in descending order based on their timestamps.

NOTE:
By default, the `after` parameter value is 0, and the `before` parameter is set to the current
system time.
Always make sure to specify `before` and `after` parameters explicitly, as otherwise it may take 
a very long time for the API call to complete.

If the `trackingId` is substituted with a valid `shipmentId`, the response
contains a composition of traces of each shipment segment. 
Traces are only fetched for those segments that are either in `ongoing` or `completed` state.

The `outliers` parameter can be used to select only traces that have
been marked as outliers (if the parameter value is `true`), or only traces
that have not been marked as outliers (if the parameter value is `false`).
If the `outliers` parameter is not present, all the traces will be returned.

The `count` and `pageToken` parameters are used for pagination.

## Path parameters

- `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.

## Query parameters

- `before` number
- `after` number
- `outliers` boolean
- `mode` 'unknown' | 'normal' | 'flight' | 'transport' | 'sleep' — Tracker mode status of the device. When a tracker is in a normal mode, it can send telemetry and, for example, use its GNSS receiver if it has one. A tracker switches into flight mode once it detects that it's in an airplane, and leaves that mode once airplane lands. Transport mode has to be triggered by the user, and it's used, for example, during shipping from continent to another. Sleep mode is used when a tracker is stored in a warehouse, and it's triggered by entering or leaving some defined geofence.
- `smooth` boolean
- `pageToken` string
- `count` integer

## Response `200`

Successful.

The response body contains an array of traces within the
given time range (`after` <= timestamp <= `before`).

Traces are sorted in descending order based on their timestamps.

- object — The response body contains an array of traces, `count` is the number of returned items and `pageToken` is the next page token if available. If no traces are found, an object with an empty data array is returned. Traces are sorted in descending order based on their timestamps.
  - `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` object[]
    - `payload` object — A free format JSON object. The maximum size is 1000B.
    - `position` object — The device location
      - `accuracy` number, required — Uncertainty circle radius in meters (degree of confidence according to the 'confidence' parameter).
      - `alt` number — Altitude in meters (referenced to the WGS-84 ellipsoid) negative or positive.
      - `altaccuracy` number — Uncertainty of the altitude estimate in meters (degree of confidence according to the 'confidence' parameter).
      - `confidence` integer — Confidence level in percent for the accuracy/uncertainty. If not specified, the default is 68 (this corresponds to a 68% probability that the true position is within the accuracy/uncertainty radius of the position; the higher the number, the greater the confidence level).
      - `floor` object — The building where the measurements were taken
        - `id` string, required — The building id
        - `level` number, required — The floor in the building in integer format
        - `name` string, required — The building name
      - `heading` integer — GPS/GNSS heading in degrees, clockwise from true north. You must specify a value for this item when you specify a value for speed.
      - `lat` number, required — Latitude in WGS-84 format, decimal representation ranging from -90 to 90.
      - `lng` number, required — Longitude in WGS-84 format, decimal representation ranging from -180 to 180.
      - `satellitecount` integer — Number of GPS/GNSS satellites used for the calculation of the position fix. ('gnss' position type only)
      - `speed` integer — GPS/GNSS speed of the device (m/s). One must specify a value for this item when one specifies a value for heading.
      - `timestamp` integer — Timestamp of the position
      - `type` string — Position type, 'gnss' (satellite based), 'cell' or 'wlan' (network based)
      - `wlancount` integer — The total number of observed WLAN APs in the scan used for producing the position. ('wlan' position type only)
    - `serverTimestamp` integer — Milliseconds elapsed since 1 January 1970 00:00:00 UTC. This describes when the measurements were processed by the backend.
    - `system` object — Contains device-reported sensor data and device configuration settings. `stateVersion` property contains the version of the last known `desired` state seen by the device.
      - `client` object — Information about the client device.
        - `accelerometerSensorRange` integer[] — Specifies the range of measurable acceleration, representation unit g (9.8 m/s^2). If more than one accelerometer is available, each element in the list will represent individual accelerometer. Each value represents a single "+/-" range. For example, value 2 means that sensor is capable to measure acceleration within the range of [-2 g, +2 g].
        - `diagnosticscode` number — Device diagnostics code.
        - `diskquota` number — Available disk quota in kilobytes.
        - `firmware` string — Device firmware version information
        - `hasAccelerometerSensor` boolean — True if a device has a sensor to measure acceleration.
        - `hasAttachSensor` boolean — True if a device has a sensor to detect if the device is attached to or detached from an object.
        - `hasHumiditySensor` boolean — True if a device has a sensor to measure humidity.
        - `hasNoBattery` boolean — False if a device has a battery.
        - `hasPressureSensor` boolean — True if a device has a sensor to measure pressure.
        - `hasTamperSensor` boolean — True if a device has a sensor to detect if device is disassembled.
        - `hasTemperatureSensor` boolean — True if a device has a sensor to measure temperature.
        - `homenetwork` object[] — Information about subscriber home network - 3GPP MCC+MNC or 3GPP2 SID+NID. Dual-SIM devices can provide information on both subscriptions.
          - `mcc` integer — Mobile Country Code
          - `mnc` integer — Mobile Network Code
          - `nid` integer — Network Id, NID
          - `sid` integer — System Id, SID
        - `manufacturer` string — Manufacturer of the device (hardware)
        - `model` string — Model of the device (hardware)
        - `modules` object[] — Software information of all updateable chips.
          - `firmwareVersion` string — Installed firmware version
          - `manufacturer` string — Manufacturer name
          - `model` string — Model or chip name
        - `name` string — Name of the client software accessing the HERE API
        - `platform` string — Software platform information of the device, for example operating system name and version.
        - `version` string — Version of the client software in format X.Y.Z, where X [0..255] is a major, Y [0..255] is a minor, and Z [0..65535] is a build version number. Increase the version/build number for each release of the client.
      - `computed` object — Values computed by HERE Tracking based on other data available.
        - `moving` boolean — Asset is considered moving if the positions of two consecutive trace points differ more than the combined positioning accuracy + 100 meters.
        - `outlier` object — Indicates that HERE Tracking detected position to be a possible outlier.
          - `correctedPosition` object — HERE Tracking estimate of more correct position.
            - `accuracy` number, required — Uncertainty circle radius in meters (degree of confidence according to the 'confidence' parameter).
            - `lat` number, required — Latitude in WGS-84 format, decimal representation ranging from -90 to 90.
            - `lng` number, required — Longitude in WGS-84 format, decimal representation ranging from -180 to 180.
            - `timestamp` integer — Milliseconds elapsed since 1 January 1970 00:00:00 UTC.
          - `reason` string, required — Reason why position was considered to be an outlier.
      - `iccid` string — SIM card integrated circuit card identifier (ICCID)
      - `imsi` string — The IMSI of the device's SIM card.
      - `mode` 'unknown' | 'normal' | 'flight' | 'transport' | 'sleep' — Tracker mode status of the device. When a tracker is in a normal mode, it can send telemetry and, for example, use its GNSS receiver if it has one. A tracker switches into flight mode once it detects that it's in an airplane, and leaves that mode once airplane lands. Transport mode has to be triggered by the user, and it's used, for example, during shipping from continent to another. Sleep mode is used when a tracker is stored in a warehouse, and it's triggered by entering or leaving some defined geofence.
      - `phoneNumber` string — The phone number of the device's SIM card in the international E.164 format. All the country codes should be prefixed a with "+" instead of "00".
      - `reportedSensorData` object — The last known device sensor data reported by the device.
        - `accelerationG` number — A g-force value of acceleration.
        - `batteryIsCharging` boolean — True if device battery is charging.
        - `batteryLevel` integer — A value of percentage battery level.
        - `deviceIsAttached` boolean — True if device is attached to an object.
        - `deviceIsStationary` boolean — True if device hasn't detected movement.
        - `deviceIsTampered` boolean — True if device is tampered.
        - `pressureHpa` number — A value of pressure in hectopascal.
        - `relativeHumidity` number — A value of relative humidity in percent.
        - `temperatureC` number — A value of temperature in celcius.
        - `tiltDegree` number — A value of tilt in degrees.
      - `stateVersion` integer — The version of the state of a device. This should be incremented only by HERE Tracking.
    - `timestamp` integer — Milliseconds elapsed since 1 January 1970 00:00:00 UTC. Specifies the time the device telemetry measurements were taken.
    - `trackingDisabled` string[] — Array containing the properties that were removed from the original device data as per disableTracking property in the device shadow. `position` refers to all positioning data and `sensors` to all reported sensor data.

## 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)