A delivery dashboard can look better simply by excluding parcels that never produced usable events. A useful report starts with the cohort definition and shows how many records were eligible for each metric. The median alone does not explain the data behind it.
Trace analytics groups account-owned shipment records created in the chosen window. That is a shipment-creation cohort, not necessarily an order-purchase cohort, and it should be labeled accordingly.
Define the population before calculating the metric
GET /v1/analytics?days=30 returns carrier and destination cohorts over a 1–90 day window. The denominator includes records without verified events. A cohort with 100 records and 20 eligible durations should not be described as measuring the delivery speed of all 100 shipments.
Use the same creation window when comparing cohorts and retain the unverified count in the report. Reduce the requested window if it contains more than 20,000 records rather than silently sampling an arbitrary subset.
Keep elapsed-time eligibility explicit
Observed transit duration requires transit and delivered scans with verified UTC instants for every scan in the history used by the metric. Unknown timezones and incomplete histories are excluded. utc_duration_samples and excluded_delivered_durations explain those exclusions.
Do not subtract an order purchase timestamp from a carrier delivery scan and label it as Trace’s transit metric. Purchase-to-delivery, warehouse processing and carrier scan-to-scan duration answer different questions.
| Measure | What it answers |
|---|---|
| Created-record count | How many shipment records entered this cohort? |
| Verified observation count | How many have usable source evidence? |
| Eligible duration samples | How many can support the reported elapsed-time calculation? |
| Excluded delivered durations | Which delivered records cannot safely support that duration? |
| Median observed transit hours | What is the median among eligible observed durations? |
Export the cohort with its context
Use format=csv for a cohort table suitable for your reporting tool. Preserve the window, retrieval date and eligibility counts alongside the export. An isolated median copied into a slide loses the qualifications needed to interpret it.
cURL · account-owned analytics export
curl "https://api.traceapi.dev/v1/analytics?days=30&format=csv" \
-H "Authorization: Bearer $TRACE_API_KEY" \
--output shipment-cohorts.csvAvoid turning a small sample into a carrier ranking
A carrier cohort can differ in route, destination, service level and source availability. A lower median in a small selected sample is not a general proof that one carrier is faster. Report sample sizes and exclusions, then investigate operational differences before making a procurement decision.
Validate a report with a known fixture containing delivered, undelivered, unverified and unknown-timezone records. The denominator should retain the whole cohort while the duration sample count includes only eligible evidence.
Common questions
Is this a guaranteed delivery SLA report?
No. It describes observed scan history for eligible records in your account. It is neither an SLA nor an independent completeness or carrier-accuracy benchmark.
References & next steps
Implementation details were checked against Trace’s current API. External product details may change; verify the linked documentation before deciding.