Diagnostic Intelligence
Computed Insights & Diagnostics
Automated health heuristics that identify stalled packages, operational bottlenecks, and shipments requiring escalation.
The insights Object
Every tracking response calculates an insights object to help logistics and support operations proactively detect stalled consignments:
JSON (Illustrative Example)
insights
{
"transit_days_elapsed": 5,
"hours_since_last_scan": 96,
"is_stuck": true,
"is_late_vs_carrier_edd": null,
"delay_days_vs_carrier_edd": null,
"hub_count": 2,
"current_stage": "in_transit",
"requires_attention": true,
"attention_reason": "stuck",
"benchmark": {
"median_transit_days_for_route": null,
"sample_size": null,
"expected_delivery_by": null
}
}Computed Fields Reference
| Field | Type | Description & Computation Logic |
|---|---|---|
is_stuck |
boolean | True when a package has had no checkpoint scans for 72+ consecutive hours while remaining in active transit. |
hours_since_last_scan |
number | null | Exact elapsed hours between the current time and the most recent carrier checkpoint event. |
transit_days_elapsed |
number | null | Total days elapsed in transit. Measured from the first carrier scan, not the booking date — pre-pickup delays aren't included. |
hub_count |
number | Count of distinct sorting hubs, processing facilities, or transit centers the shipment has navigated. |
requires_attention |
boolean | Boolean trigger flag indicating a package requires operational review (stuck in transit, failed delivery attempt, or unexpected delay). |
attention_reason |
string | null | Specific trigger cause: stuck, failed_attempt, rto, exception, or null. |
current_stage |
string | Active operational lifecycle stage. See Shipment Statuses. |
benchmark |
object | Route transit benchmark data. Route-level median baselines will expand as historical volume grows. |
Integrating Stuck Detection into Operations
Instead of waiting for customers to report lost or delayed shipments, query your open shipments daily and filter for insights.requires_attention === true to raise proactive tickets with courier partners.
For step-by-step code implementations and proactive mitigation workflows, read our technical guide: How to Detect Stuck Shipments.