report_shipment_volume_trend

Shipment counts over time for a selected milestone, grouped and bucketed across the requested date range.

The right tool when the user asks "how is volume trending?" — created shipments, booked shipments, delivered shipments, etc.

Parameters

Name	Type	Required	Description
tenantId	string	Yes	The tenant to report on.
from	string	Yes	Range start (ISO timestamp).
to	string	Yes	Range end.
milestone	string	No	Lifecycle milestone to trend — e.g. created, booked, shipped, delivered.
bucket_size	string	No	Date histogram interval — hour, day, week, month.
group_by	string	No	Dimension to group the trend 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_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_country (country 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), order_type (order type), delivery_type (delivery service type), payment_mode (how the customer pays, such as prepaid or cash on delivery), status (shipment status), reason_code (reason code of the latest 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). For a custom attribute, pass its name with a leading underscore, e.g. _region. Values: merchant, carrier, carrier_account_name, pickup_location, pickup_country, pickup_city, pickup_state, dropoff_location, dropoff_country, dropoff_city, dropoff_state, ship_zone, order_type, delivery_type, payment_mode, status, reason_code, label_status, carrier_pickup_status, error_code, error_source, error_type, error_trigger, source_type, creation_source_type, update_source_type.
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. With group_by, each bucket contains a nested breakdown by the chosen dimension.

Example agent prompts

"Daily booked shipments over the last 30 days."

report_shipment_volume_trend(
  tenantId="…",
  from="2026-04-07",
  to="2026-05-07",
  milestone="booked",
  bucket_size="day"
)

"Weekly delivered volume by carrier for Q1."

report_shipment_volume_trend(
  tenantId="…",
  from="2026-01-01",
  to="2026-03-31",
  milestone="delivered",
  bucket_size="week",
  group_by="carrier"
)

Related tools

• report_shipment_status_summary — current snapshot rather than trend.
• report_failed_delivery_analysis — failure-focused trend.
• report_carrier_performance — performance KPIs for the carriers returned by group_by="carrier".

Equivalent in the dashboard

Reports → Shipment Volume Trend.