report_exception_history

Shipment errors over time, grouped by a selected dimension.

Broader than report_failed_delivery_analysis — this report covers all exception types (booking errors, label errors, status errors, delivery failures), not just last-mile delivery failures.

Parameters

Name	Type	Required	Description
tenantId	string	Yes	The tenant to report on.
from	string	Yes	Range start.
to	string	Yes	Range end.
group_by	string	No	Dimension to group exception trends by (default: delivery_type). Use one of these values exactly as written; do not shorten or rename them: merchant (brand or store the shipment belongs to), carrier (delivery company), carrier_account (carrier account used to book the shipment), pickup_location (location the shipment is picked up from), pickup_country (country the shipment is picked up from), pickup_city (city the shipment is picked up from), dropoff_location (location the shipment is delivered to), dropoff_country (country the shipment is delivered to), dropoff_city (city the shipment is delivered to), order_type (order type), delivery_type (delivery service type), payment_mode (how the customer pays, such as prepaid or cash on delivery), shipment_type (forward or reverse shipment), error_code (error code), error_source (where the error came from), error_type (error type), error_trigger (action that triggered the error). Values: merchant, carrier, carrier_account, pickup_location, pickup_country, pickup_city, dropoff_location, dropoff_country, dropoff_city, order_type, delivery_type, payment_mode, shipment_type, error_code, error_source, error_type, error_trigger.
bucket_size	string	No	Date histogram interval — hour, day, week, month.
shipment_type	string	No	forward or reverse.
select	string	No	json-mask syntax.
merchant / location_access / country_access	string | string[]	No	Standard scope filters.

Returns

A bucketed time series of exceptions, optionally split by group_by.

Example agent prompts

"What kinds of errors are we seeing this week?"

report_exception_history(
  tenantId="…",
  from="2026-04-30",
  to="2026-05-07",
  group_by="error_type"
)

"Daily booking errors by carrier for the last month."

report_exception_history(
  tenantId="…",
  from="2026-04-07",
  to="2026-05-07",
  group_by="carrier",
  bucket_size="day"
)

Related tools

• report_failed_delivery_analysis — narrower view focused on delivery failures specifically.
• report_carrier_performance — comparative view.
• get_shipment_list (filtered with error_or_missing_label=true) — drill into individual exception shipments.

Equivalent in the dashboard

Reports → Shipment Error / Exception History.