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

# Get Active Trips

> Get devices currently in motion with their active trip data.

Returns devices currently in motion based on each device's latest GPS sample. Results are automatically scoped to devices you have access to.

## Query parameters

<ParamField query="hardware_ids" type="string[]">
  Filter by hardware IDs. Repeated or comma-separated.
</ParamField>

<ParamField query="maxAgeSeconds" type="number" default="300">
  Maximum age of latest GPS sample in seconds. Devices with older data are excluded.
</ParamField>

<ParamField query="lookbackSeconds" type="number" default="14400">
  How far back to load GPS history for trip detection.
</ParamField>

<ParamField query="speedThreshold" type="number" default="3">
  km/h — below this speed is considered stopped.
</ParamField>

<ParamField query="minimalTripDuration" type="number" default="300">
  Seconds — minimum moving time to count as a trip.
</ParamField>

<ParamField query="minimalTripDistance" type="number" default="500">
  Meters — minimum distance to count as a trip.
</ParamField>

<ParamField query="minimalParkingDuration" type="number" default="180">
  Seconds — minimum stopped time to end a trip.
</ParamField>

<ParamField query="minimalNoDataDuration" type="number" default="1800">
  Seconds — data gaps longer than this are treated as stops.
</ParamField>

<ParamField query="minimalAvgSpeed" type="number" default="1">
  km/h — minimum average speed to count as a trip.
</ParamField>

<ParamField query="maxAcceleration" type="number" default="10">
  m/s² — filter GPS spikes exceeding this value.
</ParamField>

## Response

<ResponseField name="activeTrips" type="object[]" required>
  <Expandable title="Active trip object">
    <ResponseField name="hardware_id" type="string" required>Device hardware ID.</ResponseField>
    <ResponseField name="speed" type="number" required>Current speed in km/h.</ResponseField>
    <ResponseField name="last_position_at" type="string" required>Timestamp of latest GPS fix.</ResponseField>
    <ResponseField name="last_position_age_seconds" type="number" required>Age of latest position in seconds.</ResponseField>
    <ResponseField name="location" type="object" required>Current coordinates (`lat`, `long`).</ResponseField>
    <ResponseField name="trip" type="object" required>Active trip data (same shape as trip objects in Get Trips).</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="summary" type="object" required>
  <Expandable title="Summary">
    <ResponseField name="activeCount" type="number" required>Number of devices currently in motion.</ResponseField>
    <ResponseField name="devicesQueried" type="number" required>Number of devices checked.</ResponseField>
    <ResponseField name="configUsed" type="object" required>Trip detection parameters used.</ResponseField>
    <ResponseField name="maxAgeSeconds" type="number" required>Max age filter applied.</ResponseField>
    <ResponseField name="lookbackSeconds" type="number" required>Lookback window applied.</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl -H "X-API-Key: YOUR_API_KEY" \
    "https://your-api-host/trips/active?hardware_ids=ABC123&hardware_ids=DEF456"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "activeTrips": [
      {
        "hardware_id": "ABC123",
        "speed": 19.6,
        "last_position_at": "2025-12-17T10:30:00.000Z",
        "last_position_age_seconds": 24,
        "location": { "lat": 37.7749, "long": -122.4194 },
        "trip": {
          "startTime": "2025-12-17T09:50:00.000Z",
          "endTime": "2025-12-17T10:30:00.000Z",
          "startLocation": { "lat": 37.7601, "long": -122.4312 },
          "endLocation": { "lat": 37.7749, "long": -122.4194 },
          "distance": 5234,
          "duration": 2400,
          "maxSpeed": 45.2,
          "avgSpeed": 7.8,
          "pointCount": 54
        }
      }
    ],
    "summary": {
      "activeCount": 1,
      "devicesQueried": 2,
      "configUsed": {
        "speedThreshold": 3,
        "minimalTripDuration": 300,
        "minimalTripDistance": 500,
        "minimalParkingDuration": 180,
        "minimalNoDataDuration": 1800,
        "minimalAvgSpeed": 1,
        "maxAcceleration": 10
      },
      "maxAgeSeconds": 300,
      "lookbackSeconds": 14400
    }
  }
  ```
</ResponseExample>