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	Group failure breakdown by a dimension (carrier, merchant, location, etc.).
failed_delivery_group_by	string	No	Sub-dimension for failure-reason analysis.
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"
)

"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.