search_flights

io.github.dimabalony/whentofly · Verify this server

Find the cheapest round-trip across a FLEXIBLE multi-month date window with a min/max trip length — e.g. "10–15 days, anytime Sep–Nov". Search a broad date window rather than requiring the traveler to choose exact dates first. First call the search_locations MCP tool for city or airport names, then pass each returned airport:AAA or city:AAA value unchanged as origin/destination (explicit legacy IATA codes remain supported). Add an earliest/latest date window and min/max trip duration; get back a ranked list of the cheapest fares (with booking links) plus a price verdict — an honest read of whether the cheapest fare is low, typical, or high versus the route's usual price, or unknown when we lack a usable typical-price band (a price-level read, not a buy-now-or-wait timing prediction). Non-economy requests may return action-bound Google Flights seller quotes or separate route-price evidence in metadata.route_price_check. For a specific route, set checked_bags=1 when the traveler needs one checked bag, then inspect each result's price_basis; anywhere discovery does not support baggage pricing. Checked-bag searches still run seller enrichment but set the fare-only verdict and metadata.route_price_check to null; verify=full does not override that boundary. Use it for any flight question where the dates are flexible or the user wants the cheapest time to fly. If metadata.refresh_hint is present, you may repeat the same call after the suggested delay to inspect a separate same-route/date/cabin price check. If you can wait longer for that best-effort cross-check, set verify=full. It uses a longer ~35s budget, but never treats a different airline, itinerary, gate, or booking URL as verification of the displayed offer. Provider failure, unavailability, or a spend cap can still return only cached indicators; always inspect metadata.seller_enrichment_status (`applied` means complete date-pair coverage put Serp-derived seller data in results; `complete` means the selected plan and action resolution completed without such data entering results; `partial` means date-pair or direct-action coverage has gaps though valid seller data may still rank; `skipped` is reserved for response surfaces where enrichment does not apply) and metadata.seller_enrichment_coverage. That object reports the theoretical query-valid date pairs and how many were targeted/searched; it is not exhaustive provider inventory. Default requests target at most three pairs, while explicit verify=full targets at most seven with bounded longer budgets. Inspect metadata.freshness, and metadata.route_price_check.