> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.hellotracks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Tracks

> Retrieve historical GPS track data and mileage information.

Retrieve GPS track entries (recorded location history) for members over a specified time period. Each track entry represents a continuous movement segment with detailed statistics about distance, speed, altitude, and encoded path data.

### REQUEST

```shell theme={null}
POST https://api.hellotracks.com/api/gettracks

{
  "data": {
    "from": 1634567890000,
    "until": 1634654290000,
    "uids": [
      "<member-uid-1>",
      "<member-uid-2>"
    ],
    "withCourse": false
  }
}
```

**Legacy format (deprecated but still supported):**

```shell theme={null}
POST https://api.hellotracks.com/api/gettracks

{
  "data": {
    "from": 1634567890000,
    "until": 1634654290000,
    "accounts": [
      "<uid-or-username>",
      "<uid-or-username>"
    ]
  }
}
```

<ParamField body="from" type="long" required>
  Start timestamp in milliseconds (Unix epoch). **Required.**

  Defines the beginning of the time range for track retrieval.

  Example: `1634567890000` (October 18, 2021)
</ParamField>

<ParamField body="until" type="long" required>
  End timestamp in milliseconds (Unix epoch). **Required.**

  Defines the end of the time range for track retrieval.

  Example: `1634654290000` (October 19, 2021)
</ParamField>

<ParamField body="uids" type="array">
  Array of member UIDs to retrieve tracks for. **Recommended format.**

  * If provided: Returns tracks for specified members only
  * If omitted: Uses legacy `accounts` parameter

  Example: `["abc123", "def456"]`
</ParamField>

<ParamField body="accounts" type="array">
  **Legacy parameter.** Array of UIDs or usernames. Use `uids` instead for new integrations.

  Example: `["worker1@company.com", "worker2uid"]`
</ParamField>

<ParamField body="withCourse" type="boolean" default={false}>
  Include detailed course/heading information in encoded format.

  * `true`: Adds `course_encoded` field with directional data
  * `false`: No course data (smaller response)
</ParamField>

### Permissions

* Must have view permissions for the requested members
* Can only retrieve tracks for members in your organization or network
* Company members can view employee tracks based on their role

### RESPONSE

**Modern format (when using `uids`):**

```shell theme={null}
{
  "status": 0,
  "tracks": [
    {
      "id": 13787157,
      "owner_uid": "je7oc8",
      "kind": "track_entry",
      "start_ts": 1447018045000,
      "end_ts": 1447021091000,
      "start_lat": 37.80146,
      "start_lng": -122.43145,
      "end_lat": 37.80122,
      "end_lng": -122.43148,
      "distance": 3503.1265,
      "waypoint_count": 275,
      "speed_avg": 4.140268,
      "speed_max": 12,
      "altitude_min": -44,
      "altitude_max": 0,
      "altitude_gain": 166,
      "altitude_loss": 159,
      "short_encoded": "cbveFpkgjVc...",
      "course_encoded": "cbveFpkgj...",
      "share_url": "https://hellotracks.com/!/@t/13787157",
      "labels": 0,
      "lat_min": 0,
      "lat_max": 0,
      "lng_min": 0,
      "lng_max": 0
    }
  ]
}
```

**Legacy format (when using `accounts`):**

```shell theme={null}
{
  "status": 0,
  "accounts": {
    "worker@company.com": [
      {
        // ... same track entry structure as above
      }
    ],
    "abc123": [
      {
        // ... track entries for this member
      }
    ]
  }
}
```

<ResponseField name="status" type="integer" required>
  Status code. `0` indicates success.
</ResponseField>

<ResponseField name="tracks" type="array">
  **(Modern format)** Flat array of all track entries from all requested members.
</ResponseField>

<ResponseField name="accounts" type="object">
  **(Legacy format)** Object with keys as UIDs/usernames, values as arrays of track entries for that member.
</ResponseField>

### Track Entry Structure

Each track entry contains:

**Identity & Type:**

* `id` (long): Unique track entry identifier
* `owner_uid` (string): UID of the member who recorded this track
* `kind` (string): Entry type, typically "track\_entry"
* `labels` (integer): Label flags/categories

**Time Range:**

* `start_ts` (long): Track start timestamp in milliseconds
* `end_ts` (long): Track end timestamp in milliseconds

**Location:**

* `start_lat` (double): Starting latitude
* `start_lng` (double): Starting longitude
* `end_lat` (double): Ending latitude
* `end_lng` (double): Ending longitude

**Distance & Movement:**

* `distance` (double): Total distance traveled in meters
* `waypoint_count` (integer): Number of GPS waypoints recorded

**Speed:**

* `speed_avg` (double): Average speed in meters per second
* `speed_max` (double): Maximum speed in meters per second

**Altitude:**

* `altitude_min` (integer): Minimum altitude/elevation
* `altitude_max` (integer): Maximum altitude/elevation
* `altitude_gain` (integer): Total elevation gain in meters
* `altitude_loss` (integer): Total elevation loss in meters

**Encoded Path Data:**

* `short_encoded` (string): Polyline-encoded GPS path (Google Polyline format)
* `course_encoded` (string): Encoded heading/direction data (if `withCourse: true`)

**Bounds:**

* `lat_min`, `lat_max` (double): Latitude bounding box
* `lng_min`, `lng_max` (double): Longitude bounding box

**Sharing:**

* `share_url` (string): Public shareable URL for this track

### Use Cases

**Mileage Reporting:**
Sum `distance` values across tracks for reimbursement or tax reporting.

**Route Analysis:**
Decode `short_encoded` polyline to visualize actual paths taken.

**Performance Monitoring:**
Analyze `speed_avg` and `distance` to evaluate worker efficiency.

**GPS Breadcrumbs:**
Use `waypoint_count` and encoded paths to replay historical movements.

### Examples

<RequestExample>
  ```bash Get Tracks for Date Range theme={null}
  curl -X POST https://api.hellotracks.com/api/gettracks \
    --header 'API-Key: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    -d '{
      "data": {
        "from": 1634567890000,
        "until": 1634654290000,
        "uids": ["worker1uid", "worker2uid"]
      }
    }'
  ```

  ```bash Get Tracks with Course Data theme={null}
  curl -X POST https://api.hellotracks.com/api/gettracks \
    --header 'API-Key: YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    -d '{
      "data": {
        "from": 1634567890000,
        "until": 1634654290000,
        "uids": ["abc123"],
        "withCourse": true
      }
    }'
  ```
</RequestExample>

<Note>
  **Timestamps:** All timestamps are in milliseconds since Unix epoch (January 1, 1970 UTC). This is the standard Java/JavaScript timestamp format.
</Note>

<Note>
  **Polyline Encoding:** The `short_encoded` field uses Google's Polyline Encoding Algorithm. You can decode this using standard libraries to get the full GPS path with all waypoints.
</Note>

<Tip>
  **Distance Units:** All distances are in **meters**. Divide by 1000 to get kilometers, or multiply by 0.000621371 to get miles.
</Tip>

<Tip>
  **Speed Units:** All speeds are in **meters per second**. Multiply by 3.6 for km/h or by 2.23694 for mph.
</Tip>

### Related Endpoints

* [Locate](/api-reference/endpoint/locate) - Get current real-time locations
* [Create Report](/api-reference/endpoint/createreport) - Generate mileage and activity reports
* [Get Members](/api-reference/endpoint/getaccounts) - Retrieve member information