Skip to content
Makani Global
Create account
Developers

Trip diagnostics

Report the trips your devices carry out, then replay them in the console: where each device went, how fast, and whether its trace can be trusted.

Base URLhttps://makani-k8s.lamah.com

Before you start

Trip diagnostics is a plan feature, and reporting needs a key with the diagnostics:write scope. On a plan without it, nothing is stored: every call answers 403 TRIP_DIAGNOSTICS_NOT_INCLUDED.

Start a trip

externalRef is your own id for the job. Starting a trip again with the same id returns the same trip, so a retry is safe. roleLabels names the devices you will report, in your own words. Keep the id of the answer: the next calls use it.

POST/v1/tripsScopediagnostics:write
curl -X POST "https://makani-k8s.lamah.com/v1/trips" \  -H "x-api-key: $MAKANI_API_KEY" \  -H "content-type: application/json" \  -d '{    "externalRef": "job-48213",    "countryCode": "QA",    "roleLabels": {      "vehicle": "Courier",      "customer": "Customer"    },    "destinationLatitude": 25.3548,    "destinationLongitude": 51.4816  }'

Report positions

Send up to 500 fixes at a time. role says which device the fix is from, and recordedAt is when the device took it. Give each fix an id: a batch sent again is not stored twice, and the answer counts the repeats under duplicates.

POST/v1/trips/{tripId}/locationsScopediagnostics:write
curl -X POST "https://makani-k8s.lamah.com/v1/trips/<trip-id>/locations" \  -H "x-api-key: $MAKANI_API_KEY" \  -H "content-type: application/json" \  -d '{    "samples": [      {        "id": "fix-0001",        "role": "vehicle",        "deviceId": "device-7f3a",        "latitude": 25.2854,        "longitude": 51.531,        "speedKmh": 42,        "heading": 270,        "accuracyM": 5,        "recordedAt": "2026-10-03T09:15:00.000Z"      }    ]  }'

Report events

Send up to 200 events at a time: a reroute, an arrival, anything worth seeing on the replay. payload takes up to 4 KB of JSON.

POST/v1/trips/{tripId}/eventsScopediagnostics:write
curl -X POST "https://makani-k8s.lamah.com/v1/trips/<trip-id>/events" \  -H "x-api-key: $MAKANI_API_KEY" \  -H "content-type: application/json" \  -d '{    "events": [      {        "id": "event-0001",        "type": "reroute",        "role": "vehicle",        "payload": {          "reason": "off_route"        },        "recordedAt": "2026-10-03T09:16:30.000Z"      }    ]  }'

End the trip

End the trip when the job is done.

POST/v1/trips/{tripId}/endScopediagnostics:write
curl -X POST "https://makani-k8s.lamah.com/v1/trips/<trip-id>/end" \  -H "x-api-key: $MAKANI_API_KEY"
  • 403TRIP_DIAGNOSTICS_NOT_INCLUDEDYour plan stores no traces, so nothing was written.
  • 404TRIP_NOT_FOUNDNo trip with this id belongs to the key's project.
  • 400TRIP_EVENT_TOO_LARGEAn event's payload is over 4 KB.

Replay it in the console

Open Diagnostics in the console to replay a trip: one trace per device, never merged, with the health of each trace (gaps, clock skew, low accuracy, implausible speed), the events and the matched road. Traces are kept for 30 days unless your plan sets another period.