report_failed_delivery_analysis

Failure rates, failure trends, grouped breakdowns, attempt distributions, and shipment drilldown.

This is the workhorse tool for diagnosing where deliveries are failing and why. Pair it with report_dashboard_summary for the "daily ops standup" pattern.

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 the failed delivery trend by (default: carrier). Use one of these values exactly as written; do not shorten or rename them: carrier (delivery company), carrier_account (carrier account used to book the shipment), dropoff_country (country the shipment is delivered to), order_type (order type), delivery_type (delivery service type), reason_code (reason given for the failed attempt), carrier_status (carrier status recorded for the failed attempt), shipment_type (forward or reverse shipment), merchant (brand or store the shipment belongs to), carrier_account_name (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), pickup_state (state the shipment is picked up from), dropoff_location (location the shipment is delivered to), dropoff_city (city the shipment is delivered to), dropoff_state (state the shipment is delivered to), ship_zone (shipping zone), payment_mode (how the customer pays, such as prepaid or cash on delivery), status (shipment status), label_status (label generation status), carrier_pickup_status (carrier pickup scheduling status), error_code (error code), error_source (where the error came from), error_type (error type), error_trigger (action that triggered the error), source_type (channel the shipment came from), creation_source_type (channel that created the shipment), update_source_type (channel that last updated the shipment). Values: carrier, carrier_account, dropoff_country, order_type, delivery_type, reason_code, carrier_status, shipment_type, merchant, carrier_account_name, pickup_location, pickup_country, pickup_city, pickup_state, dropoff_location, dropoff_city, dropoff_state, ship_zone, payment_mode, status, label_status, carrier_pickup_status, error_code, error_source, error_type, error_trigger, source_type, creation_source_type, update_source_type.
failed_delivery_group_by	string	No	Dimension to group the failed attempt counts by (default: carrier). Use one of these values exactly as written; do not shorten or rename them: carrier (delivery company), carrier_account (carrier account used to book the shipment), dropoff_country (country the shipment is delivered to), order_type (order type), delivery_type (delivery service type), reason_code (reason given for the failed attempt), carrier_status (carrier status recorded for the failed attempt), shipment_type (forward or reverse shipment), merchant (brand or store the shipment belongs to), carrier_account_name (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), pickup_state (state the shipment is picked up from), dropoff_location (location the shipment is delivered to), dropoff_city (city the shipment is delivered to), dropoff_state (state the shipment is delivered to), ship_zone (shipping zone), payment_mode (how the customer pays, such as prepaid or cash on delivery), status (shipment status), label_status (label generation status), carrier_pickup_status (carrier pickup scheduling status), error_code (error code), error_source (where the error came from), error_type (error type), error_trigger (action that triggered the error), source_type (channel the shipment came from), creation_source_type (channel that created the shipment), update_source_type (channel that last updated the shipment). Values: carrier, carrier_account, dropoff_country, order_type, delivery_type, reason_code, carrier_status, shipment_type, merchant, carrier_account_name, pickup_location, pickup_country, pickup_city, pickup_state, dropoff_location, dropoff_city, dropoff_state, ship_zone, payment_mode, status, label_status, carrier_pickup_status, error_code, error_source, error_type, error_trigger, source_type, creation_source_type, update_source_type.
bucket_size	string	No	Date histogram interval — hour, day, week, month.
failed_attempts	number	No	Filter by attempt count.
failed_delivery_attempt_reason	string	No	Filter by reason code.
page, page_size, sort_by, sort_direction	—	No	Pagination on the shipment drilldown section.
select	string	No	json-mask — useful here to skip the drilldown when only summaries are needed.

Plus the standard filter set (merchant, location_access, country_access, carrier, etc.).

Returns

A composite response:

• Failure rates — totals over the date range.
• Failure trends — bucketed by bucket_size.
• Grouped breakdowns — failures by group_by.
• Attempt distributions — how many attempts before final failure.
• Drilldown — a paginated list of shipments matching the filter.

Use select to fetch only the parts you need: select="failure_rate,trends" for a chart-only view, or select="drilldown" to skip aggregates.

Example agent prompts

"Why are deliveries failing this week?"

report_failed_delivery_analysis(
  tenantId="…",
  from="2026-04-30",
  to="2026-05-07",
  failed_delivery_group_by="reason_code"
)

"Show me failures by carrier over the last quarter, weekly buckets."

report_failed_delivery_analysis(
  tenantId="…",
  from="2026-02-01",
  to="2026-04-30",
  group_by="carrier",
  bucket_size="week"
)

Related tools

• report_exception_history — broader errors (not just delivery failures).
• report_carrier_performance — comparative view across carriers.
• report_sla_compliance — failures from the SLA-impact perspective.
• get_shipment_list — drill into individual failed shipments (filter by error_or_missing_label or by status).

Equivalent in the dashboard

Reports → Failed Delivery Analysis (newer Dashboard) / Failed Delivery Reasons report.