> ## 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>"
    ]
  }
}
```

**from** `long` *required*

Start timestamp in milliseconds (Unix epoch). **Required.**

Defines the beginning of the time range for track retrieval.

Example: `1634567890000` (October 18, 2021)

**until** `long` *required*

End timestamp in milliseconds (Unix epoch). **Required.**

Defines the end of the time range for track retrieval.

Example: `1634654290000` (October 19, 2021)

**uids** `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"]`

**accounts** `array`

**Legacy parameter.** Array of UIDs or usernames. Use `uids` instead for new integrations.

Example: `["worker1@example.com", "worker2uid"]`

**withCourse** `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)

### 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": 1000001,
      "owner_uid": "a1b2c3",
      "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://live.hellotracks.com/!/@t/abc123/1000001",
      "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@example.com": [
      {
        // ... same track entry structure as above
      }
    ],
    "abc123": [
      {
        // ... track entries for this member
      }
    ]
  }
}
```

**status** `integer` *required*

Status code. `0` indicates success.

**tracks** `array`

**(Modern format)** Flat array of all track entries from all requested members.

**accounts** `object`

**(Legacy format)** Object with keys as UIDs/usernames, values as arrays of track entries for that member.

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

**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 km/h
* `speed_max` (double): Maximum speed in km/h

**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`)

`labels`, `lat_min`, `lat_max`, `lng_min` and `lng_max` are currently always `0`; don't rely on them.

**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

```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
    }
  }'
```

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

> [!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.

> [!TIP]
>
> **Distance Units:** All distances are in **meters**. Divide by 1000 to get kilometers, or multiply by 0.000621371 to get miles.

> [!TIP]
>
> **Speed Units:** All speeds are in **km/h**. Multiply by 0.621371 for mph.

### Related Endpoints

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.