Incident report, and what it taught us
We build fleet visibility on the Samsara API for roofing, restoration and logistics companies. This page is not a brochure. It is what we learned shipping it, including the part where we got it wrong in front of the owner.
A wall display in a restoration company's office showed a dashcam still of a truck parked in the yard, badged 5:01 PM. The truck was not in the yard. The image was three days old, and the timestamp had no date on it, so nobody could tell.
The cause was not our rendering. It was an undocumented behavior in the media endpoint, and it was hiding in every fleet we would ever connect. Everything below exists because of that afternoon.
One live dashboard for a South Florida restoration company: the whole fleet on a map with weather radar, a card per vehicle showing its newest dashcam still and exactly where it is, and a strip of the newest field photos from the job sites.
Vehicles, vehicle statistics and camera media from Samsara. Job photos and projects from CompanyCam. Open-Meteo and RainViewer for conditions and radar, both keyless.
Every route proxies live vendor data on request. No cron, no archive, no heartbeat layer. Neither API token ever reaches the browser, and dashcam bytes are streamed rather than handing out vendor URLs.
Built to be read across a room by people who are not looking for it. Allowlisted authentication. Every timestamp carries a date and a freshness verdict.
Verified live against a real organization in August 2026, not read from documentation. These are the things that cost us time, and the reason a second integration goes in faster than the first.
/cameras/media returns at most 100 rows per response, oldest first, and silently ignores limit. We tested at 200, 512 and 1000. All three returned exactly 100.
Both halves matter together. Ask for seven vehicles across 24 hours and you get the oldest 100 frames of that window, then it stops. The newest frame, which is the entire point of the endpoint, sits on page two. This is the bug that put a three-day-old picture on the wall. Five of seven vehicles were affected, one of them driving at the time, while a 54-minute-old frame waited on page three.
The failure scales with how busy the fleet is. It is invisible on a quiet weekend and worst on the morning everyone is out working. Page with after=<endCursor>; hasNextPage is honest.
Media rows arrive under data.media, not data[] and not media[]. Reading one level too shallow returns undefined, which looks exactly like this fleet has no cameras, with no error raised anywhere.
Omitting vehicleIds is a 400, not an unfiltered query. Pass the roster explicitly. Windows wider than a single day also return 400.
They carry X-Amz-Expires=28800. A URL placed in the DOM works all afternoon and breaks silently that night, which is the worst possible failure shape for a display nobody is watching. We proxy the bytes instead of handing out the URL.
What comes back are stills with a triggerReason of periodicStill, tripStartStill, tripEndStill or safetyEvent. That cadence is the ceiling on freshness, not your poll rate. Polling harder does not make the picture newer, and promising an owner live video is a promise the platform cannot keep.
A parked truck simply produces no new frame. That is normal and must be rendered as normal, not as an error.
On a given organization these can return empty without raising an error. Audit the license matrix before promising a customer anything beyond GPS, because the demo will work on your org and quietly show nothing on theirs.
CompanyCam sends 0,0 for a photo with no GPS fix. That is null island, not the Gulf of Guinea, and on this fleet two of four uploaders send it on every photo because location is off on those handsets. That is half the photo volume. Guard for it anywhere coordinates become a place.
Its per_page also caps at 50 silently, and its photo CDN URLs are public, permanent and geotagged, so anything customer-facing needs them stripped first.
Four rules, written the day after the wall display lied. One module decides staleness, and every surface that renders a timestamp goes through the same badge.
5:01 PM is indistinguishable from the same minute three days ago. Cheapest guard here, and the one that would have caught the original bug on its own.The rules above are not documentation. They are visible in the product on every card.
Nobody who runs trucks wants a dashboard. They want to stop calling people to find out where things are, and they want to trust what the screen says without walking outside to check.
That second part is the whole game. A fleet display that is wrong once is never trusted again, and the owner goes back to the phone. Which is why the unglamorous half of this page, the pagination order and the date on the timestamp, is the half that decides whether the system gets used at all.
We build the rest of the operation around it too: CRM, field photography, voice intake, scheduling and federal bid pipelines. Telematics data is most valuable when it stops being a separate screen.
Telematics is most valuable when it stops being a separate screen. The same client runs these alongside the fleet wall.
We build and run the operational systems that roofing, restoration and logistics companies depend on, and we are a Samsara integrator in production today. Integration-first, no hardware resale.