TerraGo API

Trips

Live and historical trips. Start and complete/close a trip, stream and batch GPS breadcrumbs, fetch the latest location and a trip summary, raise and list per-trip alerts and events, and record/read per-trip device metrics.

11 endpoint(s)
GET List Trips {{url}}/trips ▸

Retrieve a paginated list of trips — actual runs a vehicle makes (as opposed to trip planners, which are the schedule templates). Trips currently ACTIVE are enriched with live occupancy (how many children have actually boarded vs. the expected roster count).

Query Parameters

  • per_page (integer, optional, default 10, max 20)
  • user_id (string UUID, optional): Filter by driver.
  • supervisor_id (string UUID, optional): Filter to a school's trips.
  • tripplannerid (string UUID, optional): Filter to trips created from a specific planner.
  • route_id (string UUID, optional): Filter by route.
  • status (string, optional): ACTIVE, COMPLETED, CANCELLED, or N/A.
  • date_range (string, optional): "YYYY-MM-DD,YYYY-MM-DD", filters by creation date.
  • search (string, optional): Matches zone/location name or trip description.

Response

Paginated list of trips (data) with meta; each: zone, staff, route, status, type, start/end times and occupancy.

Auth
Bearer token
Used On
Trip MonitoringRoute Profile
Request Body
{
    "date_range": ["2025-10-23 14:03:21", "2025-10-23 14:03:21"],
    "status": "ACTIVE",  //only use: ACTIVE,COMPLETED,CANCELLED,N/A
    "per_page": 10,
    "page": 1
}
Sample Response (200 OK)
{
    "data": [
        {
            "id": "5617575e-1567-4ca9-9aa1-04e518767e3f",
            "staff": {
                "id": "0e02c849-6f36-4fb9-81d3-64a22908ee5a",
                "first_name": "Collins",
                "middle_name": null,
                "last_name": "Muriuki"
            },
            "trip_description": "Morning Trip",
            "status": "Active",
            "start_time": "2025-12-05 13:31:43",
            "end_time": "2025-12-05 13:55:26"
        },
        {
            "id": "58f7f1e6-5b1c-48a6-a1c1-7ed00106292f",
            "staff": {
                "id": "0e02c849-6f36-4fb9-81d3-64a22908ee5a",
                "first_name": "Collins",
                "middle_name": null,
                "last_name": "Muriuki"
            },
            "trip_description": "Evening Trip",
            "status": "Active",
            "start_time": "2025-12-05 13:55:08",
            "end_time": "2025-12-05 13:55:26"
        }
    ],
    "links": {
        "first": "https://terragostg.terrasofthq.com/api/trips?page=1",
        "last": "https://terragostg.terrasofthq.com/api/trips?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "page": null,
                "active": false
            },
            {
                "url": "https://terragostg.terrasofthq.com/api/trips?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "page": null,
                "active": false
            }
        ],
        "path": "https://terragostg.terrasofthq.com/api/trips",
        "per_page": 15,
        "to": 2,
        "total": 2
    },
    "status": 200,
    "message": "Trips Retrieved Successfully"
}
POST Start Trip {{url}}/trips/add ▸

Start a new trip by instantiating a trip planner against a route — i.e. the driver taps "Start Trip" for today's run.

Request Body

  • trip_description (string, required): Free-text notes about this run.
  • tripplannerid (string UUID, required): Must reference an existing trip planner.
  • route_id (string UUID, required): Must reference an existing route.
  • waaszoneuuid / waaszonename (string, optional): The vehicle/zone/location running the trip.

Notes

  • If the same zone/location/vehicle already has an ACTIVE trip started by a different driver, this returns a 409 Conflict — a vehicle can't run two trips at once.
  • If the same driver calls this again while their own trip is still active, the existing trip is returned instead of creating a duplicate (safe to retry).
  • Vehicle capacity for occupancy calculations is read from the driver's assigned-zone/location metadata.
Auth
Bearer token
Request Body
{
    "trip_planner_id": "da2175e7-cc4d-4c25-a8e8-4ad81300a9e1",  // Trip planner UUID (which trip this belongs to)
    "trip_description" : "Evening Trip",  // Optional note describing the trip
    "waas_zone_uuid": "abb58804-ae3f-4bf4-8073-9ac8b7e0c257",  // Zone/location UUID (from the WaaS partner system)
    "waas_zone_name": "TerraHQ",  // Zone/location display name
    "route_id": "643ab899-5b74-4dc1-b3a0-5b512dc11336"  // Route UUID
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "id": "ff221831-a3c7-4408-945a-4e84408d5779",
        "staff": {
            "id": "68b86410-e6e8-4b5f-9a3d-8265a7773c0e",
            "first_name": "Jane",
            "middle_name": "Wanjiku",
            "last_name": "Otieno"
        },
        "zone_id": "abb58804-ae3f-4bf4-8073-9ac8b7e0c257",
        "trip_description": "Evening Trip",
        "waas_zone_name": "TerraHQ",
        "waas_zone_uuid": "abb58804-ae3f-4bf4-8073-9ac8b7e0c257",
        "status": "Active",
        "end_time": null,
        "start_time": "2025-12-25 09:19:10",
        "route": {
            "id": "643ab899-5b74-4dc1-b3a0-5b512dc11336",
            "name": "Kiota School Rongai Route",
            "description": "Kiota School Rongai Route for students",
            "waas_zone_name": "Terra Hq",
            "waas_zone_uuid": "ada52fc6-d481-48d9-82b3-fddb07d5d44f",
            "est_duration": "120",
            "status": "Active"
        }
    },
    "message": "Trip Created Successfully"
}
PUT Update / Complete Trip {{url}}/trips/update/d5d46e78-8792-4cee-aec6-a43dbdbc4716 ▸

Update a trip's description or mark it as finished. This is how a trip is completed — set status to COMPLETED with an end_time.

Path Parameters

  • id (string UUID, required): Trip UUID.

Request Body

  • trip_description (string, optional): Updated notes.
  • status (string, required): ACTIVE, COMPLETED, CANCELLED, or N/A.
  • end_time (datetime, required): Format Y-m-d H:i:s.

Side Effects

  • When status=COMPLETED and end_time is set, a background job builds a downloadable "trip file" (route + GPS history export) for the trip.

Response

The updated (or completed) trip (data).

Auth
Bearer token
Used On
Trip Monitoring
Request Body
{
    "trip_description" : "Morning Trip",
    "status": "COMPLETED", //only use: ACTIVE,COMPLETED,CANCELLED,N/A
    "end_time" : "2026-06-06 12:12:12", //format:Y-m-d H:i:s
    "absent": 0
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "id": "d5d46e78-8792-4cee-aec6-a43dbdbc4716",
        "staff": {
            "id": "68b86410-e6e8-4b5f-9a3d-8265a7773c0e",
            "first_name": "Jane",
            "middle_name": "Wanjiku",
            "last_name": "Otieno"
        },
        "zone_id": "abb58804-ae3f-4bf4-8073-9ac8b7e0c257",
        "trip_description": "Morning Trip",
        "waas_zone_name": "TerraHQ",
        "waas_zone_uuid": "abb58804-ae3f-4bf4-8073-9ac8b7e0c257",
        "status": "Completed",
        "end_time": "2026-06-06 12:12:12",
        "start_time": "2025-12-25 09:13:54",
        "route": {
            "id": "643ab899-5b74-4dc1-b3a0-5b512dc11336",
            "name": "Kiota School Rongai Route",
            "description": "Kiota School Rongai Route for students",
            "waas_zone_name": "Terra Hq",
            "waas_zone_uuid": "ada52fc6-d481-48d9-82b3-fddb07d5d44f",
            "est_duration": "120",
            "status": "Active"
        }
    },
    "message": "Trip Updated Successfully"
}
GET List Trip GPS Locations {{url}}/trips/1df71287-def7-44fd-91f6-9470bed18f28/trip-locations ▸

Retrieve the GPS breadcrumb trail recorded for a trip.

Path Parameters

  • id (string UUID, required): Trip UUID.

Query Parameters

  • per_page (integer, optional, default 10, max 20)
  • date_range (string, optional): "YYYY-MM-DD,YYYY-MM-DD", filters by when the point was recorded.

Response

List of GPS breadcrumbs (data) for the trip — latitude, longitude, recorded_at.

Auth
Bearer token
Request Body
{
    // "date_range": "2025-10-23 14:03:21,2025-10-23 14:03:21",
    "per_page": 10,
    "page": 1
}
Sample Response (200 OK)
{
    "data": [],
    "links": {
        "first": "https://terragostg.terrasofthq.com/api/trips/1df71287-def7-44fd-91f6-9470bed18f28/trip-locations?page=1",
        "last": "https://terragostg.terrasofthq.com/api/trips/1df71287-def7-44fd-91f6-9470bed18f28/trip-locations?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": null,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "page": null,
                "active": false
            },
            {
                "url": "https://terragostg.terrasofthq.com/api/trips/1df71287-def7-44fd-91f6-9470bed18f28/trip-locations?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "page": null,
                "active": false
            }
        ],
        "path": "https://terragostg.terrasofthq.com/api/trips/1df71287-def7-44fd-91f6-9470bed18f28/trip-locations",
        "per_page": 10,
        "to": null,
        "total": 0
    },
    "status": 200,
    "message": "Trip Locations Retrieved Successfully"
}
POST Add Trip GPS Locations (Batch) {{url}}/trips/trip-locations/add ▸

Submit one or more GPS coordinates for a trip in a single batch call — the app buffers points while offline/moving and flushes them here.

Request Body

  • trip_id (string UUID, required): Trip these points belong to.
  • coordinates (array, required, min 1 item):
  • coordinates[].latitude (number, required, -90 to 90)
  • coordinates[].longitude (number, required, -180 to 180)
  • coordinates[].recorded_at (datetime, required): Y-m-d H:i:s, when the device actually captured the point (not when it was uploaded).
  • coordinates[].metadata (object, optional): Arbitrary extra data (e.g. speed, heading).

Notes

  • Rejected if the target trip is already COMPLETED (has an end_time) — you cannot append locations to a finished trip.
  • Points are processed asynchronously after being accepted.

Response

Confirmation of how many points were stored (data).

Auth
Bearer token
Request Body
{
    "trip_id": "a6a0e8a2-057c-40ac-bed1-4e49fb050f7d",
    "coordinates": [
        {
        "latitude": -1.2921,
        "longitude": 36.8219,
        "recorded_at": "2026-03-16 11:20:00" //format:Y-m-d H:i:s
        },
        {
        "latitude": -1.2922,
        "longitude": 36.8220,
        "recorded_at": "2026-03-16 11:20:05" //format:Y-m-d H:i:s
        },
        {
        "latitude": -1.2923,
        "longitude": 36.8222,
        "recorded_at": "2026-03-16 11:20:10" //format:Y-m-d H:i:s
        }
    ]
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {},
    "message": "Trip Location Added Successfully"
}
GET Get Latest Trip GPS Location {{url}}/trips/a6a0e8a2-057c-40ac-bed1-4e49fb050f7d/trip-locations/latest ▸

Fetch only the most recent GPS coordinate recorded for a trip — useful for a lightweight "where is the bus right now" poll instead of pulling the full breadcrumb trail.

Path Parameters

  • id (string UUID, required): Trip UUID.

Response

The single most recent GPS point (data) for the trip.

Auth
Bearer token
Request Body
{
    "date_range": "2025-10-23 14:03:21, 2025-10-23 14:03:21",
    "status": "ACTIVE",  //only use: ACTIVE,COMPLETED,CANCELLED,N/A
    "per_page": 10,
    "page": 1
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "id": "6dc23c9d-3e98-4e8d-bb0d-d9810d77b386",
        "trip_id": "a6a0e8a2-057c-40ac-bed1-4e49fb050f7d",
        "longitude": "36.8090657",
        "latitude": "-1.2622458",
        "recorded_at": "2026-01-07 12:07:51"
    },
    "message": "Trip Location Retrieved Successfully"
}
GET Get Trip Summary {{url}}/trips/single_summary/cb4a018b-0e0a-4f72-bc3d-33faa54c18ad ▸

Get summary statistics for a trip: duration, how many children were expected vs. actually boarded, and how they were checked in (NFC scan vs. manual roll call).

Path Parameters

  • id (string UUID, required): Trip UUID.

Response

{
  "trip_duration": { "hours": 0, "minutes": 45, "seconds": 12, "formatted": "0 hours, 45 minutes, 12 seconds", "short": "00:45:12" },
  "device_scans": 18,
  "manual": 2,
  "expected_occupancy": 22,
  "current_occupancy": 20,
  "active_occupancy": 20,
  "absent": 2
}

Notes

  • tripduration is calculated from starttime to end_time, so this is most meaningful for a completed trip.
Auth
Bearer token
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "trip_duration": {
            "hours": 0,
            "minutes": 14,
            "seconds": 14,
            "formatted": "0 hours, 14 minutes, 14 seconds",
            "short": "00:14:14"
        },
        "device_scans": 0,
        "manual": 0,
        "expected_occupancy": 20,
        "current_occupancy": 0,
        "active_occupancy": 0,
        "absent": 3
    },
    "message": "Single Trip Summary Fetched Successfully"
}
GET List Trip Alerts & Events {{url}}/trips/87fe938c-b69c-4908-a9a1-5f7e8ea9aba8/trip-alerts ▸

List the alerts and events (e.g. SOS, speeding, geofence exit, flat tire) raised during a specific trip.

Path Parameters

  • id (string UUID, required): Trip UUID.

Query Parameters

  • per_page (integer, optional, default 10, max 20)
  • severity (string, optional): INFO, WARNING, or CRITICAL.
  • eventtype (string, optional): FLATTIRE, STOP, SPEEDING, GEOFENCE_EXIT, SOS, INCIDENT, or CUSTOM.
  • date_range (string, optional): "YYYY-MM-DD,YYYY-MM-DD", filters by when the event was recorded.

Notes

  • You only see alerts for trips you supervise.

Response

List of the trip's alerts/events (data).

Auth
Bearer token
Used On
Trip Monitoring
Request Body
{
    // "date_range": "2025-10-23 14:03:21, 2025-10-23 14:03:21",
    "per_page": 10,
    "page": 1
}
Sample Response (200 OK)
{
    "data": [
        {
            "id": "b4f33450-edbe-40e5-aba5-3a3413c9859b",
            "trip_id": "a6a0e8a2-057c-40ac-bed1-4e49fb050f7d",
            "dependant": {
                "id": 9,
                "first_name": "Simon",
                "middle_name": "Kimani",
                "last_name": "Chege"
            },
            "severity": "Info",
            "event_type": "Flat Tire",
            "event_details": "Tire Punchure",
            "message": "Dear Guardian, Bus KZA 234R has a punchure, kindly note the delay!",
            "recorded_at": "2025-06-06 12:12:12"
        },
        {
            "id": "42422678-b667-4740-b1b0-4608bcb0b72f",
            "trip_id": "a6a0e8a2-057c-40ac-bed1-4e49fb050f7d",
            "dependant": {
                "id": 7,
                "first_name": "Kids",
                "middle_name": "L",
                "last_name": "Name"
            },
            "severity": "Info",
            "event_type": "Flat Tire",
            "event_details": "Tire Punchure",
            "message": "Dear Guardian, Bus KZA 234R has a punchure, kindly note the delay!",
            "recorded_at": "2025-06-06 12:12:12"
        },
        {
            "id": "b4693a4f-98d7-474c-8bab-27545d1b0628",
            "trip_id": "a6a0e8a2-057c-40ac-bed1-4e49fb050f7d",
            "dependant": {
                "id": 9,
                "first_name": "Simon",
                "middle_name": "Kimani",
                "last_name": "Chege"
            },
            "severity": "Info",
            "event_type": "Flat Tire",
            "event_details": "Tire Punchure",
            "message": "Dear Guardian, Bus KZA 234R has a punchure, kindly note the delay!",
            "recorded_at": "2025-06-06 12:12:12"
        },
        {
            "id": "4449d8e1-3b3e-4df9-8327-6277c6362e6a",
            "trip_id": "a6a0e8a2-057c-40ac-bed1-4e49fb050f7d",
            "dependant": {
                "id": 7,
                "first_name": "Kids",
                "middle_name": "L",
                "last_name": "Name"
            },
            "severity": "Info",
            "event_type": "Flat Tire",
            "event_details": "Tire Punchure",
            "message": "Dear Guardian, Bus KZA 234R has a punchure, kindly note the delay!",
            "recorded_at": "2025-06-06 12:12:12"
        },
        {
            "id": "07987e5d-09dd-440f-b5e8-2a6ee6d14d01",
            "trip_id": "a6a0e8a2-057c-40ac-bed1-4e49fb050f7d",
            "dependant": {
                "id": 30,
                "first_name": "Junior",
                "middle_name": null,
                "last_name": "Pm"
            },
            "severity": "Info",
            "event_type": "Flat Tire",
            "event_details": "Tire Punchure",
            "message": "Dear Guardian, Bus KZA 234R has a punchure, kindly note the delay!",
            "recorded_at": "2025-06-06 12:12:12"
        },
        {
            "id": "c10691d7-77b1-4c42-9775-27dba290f8c2",
            "trip_id": "a6a0e8a2-057c-40ac-bed1-4e49fb050f7d",
            "dependant": {
                "id": 37,
                "first_name": "Middle",
                "middle_name": null,
                "last_name": "PM"
            },
            "severity": "Info",
            "event_type": "Flat Tire",
            "event_details": "Tire Punchure",
            "message": "Dear Guardian, Bus KZA 234R has a punchure, kindly note the delay!",
            "recorded_at": "2025-06-06 12:12:12"
        },
        {
            "id": "e5c66910-89e3-412c-9ec5-b5767e49f727",
            "trip_id": "a6a0e8a2-057c-40ac-bed1-4e49fb050f7d",
            "dependant": {
                "id": 30,
                "first_name": "Junior",
                "middle_name": null,
                "last_name": "Pm"
            },
            "severity": "Info",
            "event_type": "Flat Tire",
            "event_details": "Tire Punchure",
            "message": "Dear Guardian, Bus KZA 234R has a punchure, kindly note the delay!",
            "recorded_at": "2025-06-06 12:12:12"
        },
        {
            "id": "040333f9-6966-4576-aabf-a20605dd6a9f",
            "trip_id": "a6a0e8a2-057c-40ac-bed1-4e49fb050f7d",
            "dependant": {
                "id": 37,
                "first_name": "Middle",
                "middle_name": null,
                "last_name": "PM"
            },
            "severity": "Info",
            "event_type": "Flat Tire",
            "event_details": "Tire Punchure",
            "message": "Dear Guardian, Bus KZA 234R has a punchure, kindly note the delay!",
            "recorded_at": "2025-06-06 12:12:12"
        }
    ],
    "links": {
        "first": "https://terragostg.terrasofthq.com/api/trips/a6a0e8a2-057c-40ac-bed1-4e49fb050f7d/trip-alerts?page=1",
        "last": "https://terragostg.terrasofthq.com/api/trips/a6a0e8a2-057c-40ac-bed1-4e49fb050f7d/trip-alerts?page=1",
        "prev": null,
        "next": null
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
            {
                "url": null,
                "label": "« Previous",
                "page": null,
                "active": false
            },
            {
                "url": "https://terragostg.terrasofthq.com/api/trips/a6a0e8a2-057c-40ac-bed1-4e49fb050f7d/trip-alerts?page=1",
                "label": "1",
                "page": 1,
                "active": true
            },
            {
                "url": null,
                "label": "Next »",
                "page": null,
                "active": false
            }
        ],
        "path": "https://terragostg.terrasofthq.com/api/trips/a6a0e8a2-057c-40ac-bed1-4e49fb050f7d/trip-alerts",
        "per_page": 10,
        "to": 8,
        "total": 8
    },
    "status": 200,
    "message": "Alert And Events Retrieved Successfully"
}
POST Create Trip Alerts & Events {{url}}/trips/trip-alerts/add ▸

Raise an alert/event against a trip for one or more children — e.g. flagging that a specific child had an incident during the run. Creates one alert record per student listed.

Request Body

  • trip_id (string UUID, required)
  • dependant_ids (array, required): One or more child UUIDs this alert concerns.
  • severity (string, required): INFO, WARNING, or CRITICAL.
  • eventtype (string, required): FLATTIRE, STOP, SPEEDING, GEOFENCE_EXIT, SOS, INCIDENT, or CUSTOM.
  • message (string, required): Short alert text.
  • event_details (string, required): Longer description.
  • recorded_at (datetime, required): Y-m-d H:i:s.

Notes

  • Each student gets their own alert record (their parent's phone number is attached automatically), and the creation is all-or-nothing (one DB transaction).
  • This is the endpoint used when staff manually log an alert; compare to the driver-facing "raise alert mid-trip" endpoint, which is a lighter-weight, not-yet-documented-in-Postman route (POST /trips/{trip_uuid}/raise-alert).

Response

The created alert/event (data).

Auth
Bearer token
Request Body
{
    "trip_id": "3c290b8b-417f-4cc8-aded-62a28c0c128a",
    "dependant_ids": ["e4fd1a8b-e2cd-4a69-b606-6df95fc52b58", "6d7c073f-adf2-47d4-9381-0f7889ed2bc3"],  
    "severity": "CRITICAL", //only use: INFO, WARNING, CRITICAL
    "event_type": "FLAT_TIRE", //only use: FLAT_TIRE, INCIDENT, CUSTOM
    "message": "Dear Parent, Bus KPM 234R has a punchure, kindly note the delay!",
    "event_details": "Flat Tire",
    "recorded_at" : "2026-01-20 12:12:12" //format:Y-m-d H:i:s
}
Sample Response (200 OK)
{
    "data": [
        {
            "id": "3a2ebbd7-c483-4ba5-987d-ffe1b1812dd5",
            "trip_id": "a6a0e8a2-057c-40ac-bed1-4e49fb050f7d",
            "dependant": {
                "id": 30,
                "first_name": "Junior",
                "middle_name": null,
                "last_name": "Pm"
            },
            "severity": "Info",
            "event_type": "Flat Tire",
            "event_details": "Tire Punchure",
            "message": "Dear Guardian, Bus KZA 234R has a punchure, kindly note the delay!",
            "recorded_at": "2025-06-06 12:12:12"
        },
        {
            "id": "b40a2131-4796-429d-977b-962f275a1dd2",
            "trip_id": "a6a0e8a2-057c-40ac-bed1-4e49fb050f7d",
            "dependant": {
                "id": 37,
                "first_name": "Middle",
                "middle_name": null,
                "last_name": "PM"
            },
            "severity": "Info",
            "event_type": "Flat Tire",
            "event_details": "Tire Punchure",
            "message": "Dear Guardian, Bus KZA 234R has a punchure, kindly note the delay!",
            "recorded_at": "2025-06-06 12:12:12"
        }
    ],
    "status": 200,
    "message": "Alert And Events Added Successfully"
}
GET List Trip Device Metrics {{url}}/trips/3bc5f24d-515d-4266-8899-144d8a47a9f5/trip-device-metrics ▸

List the telemetry snapshots (battery, signal strength, data usage, uptime, etc.) reported by the onboard tracking device during a trip, most recent first.

Path Parameters

  • uuid (string UUID, required): Trip UUID.

Response

The device-metrics records (data) for the trip.

Auth
Bearer token
Sample Response (200 OK)
{
    "status": 200,
    "data": [
        {
            "id": "7413179e-6153-4196-b6b1-b00f0115f629",
            "battery": {
                "start": 85,
                "end": 62,
                "drop": 23
            },
            "network": {
                "signal_avg": -67,
                "signal_min": -89,
                "signal_max": -55,
                "lte": true,
                "network_type": "4G",
                "disconnect_count": 2,
                "offline_duration_seconds": 45
            },
            "data": {
                "usage_mb": "14.75",
                "upload_bytes": 10485760
            },
            "activity": {
                "gps_points_count": 320,
                "scan_events_count": 18,
                "expected_students": 45,
                "detected_students": 43
            },
            "device": {
                "firmware": "v1.2.3",
                "uptime_seconds": 5400
            },
            "created_at": "Fri, Jun 12, 2026 12:31 PM",
            "updated_at": "Fri, Jun 12, 2026 12:31 PM"
        }
    ],
    "message": "Device Metrics Retrieved Successfully"
}
POST Record Trip Device Metrics {{url}}/trips/3bc5f24d-515d-4266-8899-144d8a47a9f5/trip-device-metrics/add ▸

Submit a telemetry snapshot from the onboard tracking device for a trip (battery level, cellular signal, connectivity issues, data usage, scan counts, occupancy detection).

Path Parameters

  • uuid (string UUID, required): Trip UUID.

Request Body (all fields optional — send what the device has)

  • batterystarttrip / batteryendtrip (integer, 0–100)
  • signalavg / signalmin / signalmax (integer, dBm, -120 to 0), lte (boolean), networktype (string, max 20)
  • disconnectcount (integer), offlinedurationseconds (integer), datausagemb (number), uploadbytes (integer)
  • gpspointscount (integer), scaneventscount (integer), uptime_seconds (integer), firmware (string)
  • expectedstudents / detectedstudents (integer): For onboard headcount-detection hardware.

Response

The recorded device-metrics row (data).

Auth
Bearer token
Request Body
{
    "battery_start_trip": 85,
    // optional | battery level at trip start
    "battery_end_trip": 62,
    // optional | battery level at trip end
    "signal_avg": -67,
    // optional | average network signal strength (dBm)
    "signal_min": -89,
    // optional | weakest signal recorded
    "signal_max": -55,
    // optional | strongest signal recorded
    "lte": true,
    // optional | true if device used 4G LTE connection
    "network_type": "4G",
    // optional | network type (2G/3G/4G/5G)
    "disconnect_count": 2,
    // optional | number of network disconnections during trip
    "offline_duration_seconds": 45,
    // optional | total time device was offline
    "data_usage_mb": 14.75,
    // optional | total mobile data used during trip
    "upload_bytes": 10485760,
    // optional | total bytes uploaded to server
    "gps_points_count": 320,
    // optional | number of GPS tracking points recorded
    "scan_events_count": 18,
    // optional | number of student/device scan events
    "expected_students": 45,
    // optional | expected number of students for trip
    "detected_students": 43,
    // optional | actual detected students during trip
    "firmware": "v1.2.3",
    // optional | device firmware version
    "uptime_seconds": 5400
    // optional | device uptime during trip in seconds
}
Sample Response (200 OK)
{
    "status": 200,
    "data": {
        "id": "bcf0abaf-ac66-4b2a-9dcb-98f4d0378ff4",
        "battery": {
            "start": 85,
            "end": 62,
            "drop": 23
        },
        "network": {
            "signal_avg": -67,
            "signal_min": -89,
            "signal_max": -55,
            "lte": true,
            "network_type": "4G",
            "disconnect_count": 2,
            "offline_duration_seconds": 45
        },
        "data": {
            "usage_mb": 14.75,
            "upload_bytes": 10485760
        },
        "activity": {
            "gps_points_count": 320,
            "scan_events_count": 18,
            "expected_students": 45,
            "detected_students": 43
        },
        "device": {
            "firmware": "v1.2.3",
            "uptime_seconds": 5400
        },
        "created_at": "Fri, Jun 12, 2026 12:53 PM",
        "updated_at": "Fri, Jun 12, 2026 12:53 PM"
    },
    "message": "Device Metric Created Successfully"
}