whentofly

Previous value: -[
-  "2026-09-26"
-]New value: +[
+  "2026-09-29"
+]

Previous value: -[
-  "2026-12-25"
-]New value: +[
+  "2026-12-28"
+]

Added value: +{
+  "default": true,
+  "description": "Whether to run the live seller-quote wave (Google Flights `booking_options`) for this request. Default `true`: unchanged behavior — the bounded frontier resolves seller prices, baggage basis, and the executable booking action. Set `sellers=false` to ask for the ranked fare calendar and the route-level price check ONLY: the response then carries `metadata.seller_enrichment_status=\"skipped\"`, results keep their Travelpayouts-grounded prices and durable booking links, and no seller quote, seller-level baggage fee, or direct seller action is resolved. It exists for callers that want the price picture cheaply and do not intend to book — our own curve-seeding crons use it — because the seller wave is where a search's provider spend actually goes (about seven of its ~eight calls). Non-economy cabins have no calendar source, so `sellers=false` there leaves `metadata.route_price_check` as the only priced evidence and `results` may be empty.",
+  "examples": [
+    true,
+    false
+  ],
+  "title": "sellers",
+  "type": "boolean"
+}

Previous value: -"Earliest acceptable departure date (ISO YYYY-MM-DD). Optional: omit it and a default window is searched, with the applied window echoed in `query` and flagged by `metadata.window_defaulted`. Ignored in anywhere mode."New value: +"Earliest acceptable departure date (ISO YYYY-MM-DD). Optional: omit it and a default window is searched, with the applied window echoed in `query` and flagged by `metadata.window_defaulted`. A date already in the past is clamped to today and reported as `window_clamped` in `metadata.hints` — unless `latest` has passed too, in which case the whole window is declined rather than clamped (see `latest`). Ignored in anywhere mode."

Previous value: -[
-  "2026-06-01"
-]New value: +[
+  "2026-09-26"
+]

Previous value: -"Latest acceptable return date for round-trip, or latest acceptable departure for one-way (ISO YYYY-MM-DD). Window from earliest must be ≤365 days. Optional: omit it and it is derived from `earliest` (or from the default window when both are omitted). Ignored in anywhere mode."New value: +"Latest acceptable return date for round-trip, or latest acceptable departure for one-way (ISO YYYY-MM-DD). Window from earliest must be ≤365 days. Optional: omit it and it is derived from `earliest` (or from the default window when both are omitted). A window ending before today is not searched; the response is empty with a `window_in_past` hint. Ignored in anywhere mode."

Previous value: -[
-  "2026-08-31"
-]New value: +[
+  "2026-12-25"
+]

Previous value: -"Earliest acceptable departure date (ISO YYYY-MM-DD). Required for a specific route; ignored in anywhere mode."New value: +"Earliest acceptable departure date (ISO YYYY-MM-DD). Optional: omit it and a default window is searched, with the applied window echoed in `query` and flagged by `metadata.window_defaulted`. Ignored in anywhere mode."

Previous value: -"Latest acceptable return date for round-trip, or latest acceptable departure for one-way (ISO YYYY-MM-DD). Window from earliest must be ≤365 days. Required for a specific route; ignored in anywhere mode."New value: +"Latest acceptable return date for round-trip, or latest acceptable departure for one-way (ISO YYYY-MM-DD). Window from earliest must be ≤365 days. Optional: omit it and it is derived from `earliest` (or from the default window when both are omitted). Ignored in anywhere mode."

Previous value: -"Acquisition channel tag (e.g. web, mcp, a campaign name). Encoded with the route into the affiliate link's sub_id so a future commission can be attributed to this channel in the Travelpayouts dashboard. Defaults to 'direct'. Sanitized to [a-z0-9-]; capped at 64 chars."New value: +"Acquisition channel tag (e.g. web, mcp, a campaign name) for first-party analytics. Durable booking links retain the validated Travelpayouts marker for commission but do not trust opaque shortlinks solely to carry provider-dashboard sub_id attribution. Defaults to 'direct'; reduced to a bounded registered channel."

Previous value: -"How hard to cross-check the top result's route, dates, and cabin against Google Flights (SerpApi). `false` (default): the check still runs automatically on a fresh search when the top isn't already a live price, within a client-aware time budget. `true`: force the check even on a cache hit. `full`: THOROUGH mode — force the same best-effort check with a longer ~35s budget (set it when you can wait, e.g. an autonomous agent). This does not verify the displayed airline, itinerary, gate, or booking URL; inspect `metadata.route_price_check` separately. Checked-bag searches keep this fare-only route check and verdict null even when verify=true or verify=full; seller-level baggage enrichment still runs. Displayed Travelpayouts fares remain explicitly labeled cached indicators. No-op unless a SerpApi key is configured."New value: +"How hard to cross-check the top result's route, dates, and cabin against Google Flights (SerpApi). `false` (default): the check still runs automatically on a fresh search when the top isn't already a live price, within a client-aware time budget. `true`: force the check even on a cache hit. `full`: THOROUGH mode — force the same best-effort check with a longer ~35s budget and widen the request-local seller/date sample from at most three pairs to at most seven (set it when you can wait, e.g. an autonomous agent). The six-hour base and its cache key do not change. This does not verify the displayed airline, itinerary, gate, or booking URL; inspect `metadata.route_price_check` separately. Checked-bag searches keep this fare-only route check and verdict null even when verify=true or verify=full; seller-level baggage enrichment still runs. Displayed Travelpayouts fares remain explicitly labeled cached indicators. No-op unless a SerpApi key is configured."

Previous value: -"Cabin class: economy (default), premium_economy, business, or first. The bookable Travelpayouts calendar currently covers economy only. For a non-economy request, Google Flights may return representative route/date/cabin evidence in metadata.route_price_check, but no ranked fare is shown unless an exact seller booking action is available."New value: +"Cabin class: economy (default), premium_economy, business, or first. The Travelpayouts calendar covers economy; Google Flights may additionally return action-bound seller quotes for the requested cabin. Actionless evidence remains in metadata.route_price_check."

Added value: +{
+  "default": 0,
+  "description": "Checked bags requested for the current one-adult, specific-route search contract. Anywhere discovery rejects checked_bags=1. Set to 1 to add a seller's unambiguous first-checked-bag fee to the ranked customer price. Unknown fees remain labeled in results[].price_basis instead of being guessed. Seller enrichment still runs, but the fare-only verdict and route-price check remain null, including when verify=true or verify=full.",
+  "examples": [
+    0,
+    1
+  ],
+  "maximum": 1,
+  "minimum": 0,
+  "title": "checked_bags",
+  "type": "integer"
+}

Previous value: -"How hard to cross-check the top result's route, dates, and cabin against Google Flights (SerpApi). `false` (default): the check still runs automatically on a fresh search when the top isn't already a live price, within a client-aware time budget. `true`: force the check even on a cache hit. `full`: THOROUGH mode — force the same best-effort check with a longer ~35s budget (set it when you can wait, e.g. an autonomous agent). This does not verify the displayed airline, itinerary, gate, or booking URL; inspect `metadata.route_price_check` separately. Displayed Travelpayouts fares remain explicitly labeled cached indicators. No-op unless a SerpApi key is configured."New value: +"How hard to cross-check the top result's route, dates, and cabin against Google Flights (SerpApi). `false` (default): the check still runs automatically on a fresh search when the top isn't already a live price, within a client-aware time budget. `true`: force the check even on a cache hit. `full`: THOROUGH mode — force the same best-effort check with a longer ~35s budget (set it when you can wait, e.g. an autonomous agent). This does not verify the displayed airline, itinerary, gate, or booking URL; inspect `metadata.route_price_check` separately. Checked-bag searches keep this fare-only route check and verdict null even when verify=true or verify=full; seller-level baggage enrichment still runs. Displayed Travelpayouts fares remain explicitly labeled cached indicators. No-op unless a SerpApi key is configured."

Previous value: -"Origin airport, 3-letter IATA code, UPPERCASE. Required for every search, including to=anywhere."New value: +"Origin location. Use a legacy 3-letter code (SHA), an exact airport (airport:SHA), or an all-airports city (city:SHA). Required for every search, including to=anywhere."

Previous value: -[
-  "SGN",
-  "HKG",
-  "BKK"
-]New value: +[
+  "SGN",
+  "airport:SHA",
+  "city:SHA"
+]

Previous value: -"Destination airport, 3-letter IATA code, UPPERCASE. Pass `anywhere` (or omit) to get the cheapest destinations from the origin instead of a specific route."New value: +"Destination location: a legacy code, airport:AAA, or city:AAA. Pass `anywhere` (or omit) to get the cheapest destinations from the origin instead of a specific route."

Previous value: -[
-  "ICN",
-  "NRT",
-  "SIN",
-  "anywhere"
-]New value: +[
+  "ICN",
+  "airport:PVG",
+  "city:BJS",
+  "anywhere"
+]

Previous value: -"Cabin class: economy (default), premium_economy, business, or first. Use cabin=business to find business-class deals — the price verdict then judges the fare against the route's typical BUSINESS prices, and metadata.deal_signal flags a business fare below its own typical band. Non-economy cabins are priced via the live Google Flights source only (the cached calendar source covers economy), so results sample representative dates in the window."New value: +"Cabin class: economy (default), premium_economy, business, or first. The bookable Travelpayouts calendar currently covers economy only. For a non-economy request, Google Flights may return representative route/date/cabin evidence in metadata.route_price_check, but no ranked fare is shown unless an exact seller booking action is available."

Previous value: -"How hard to live-verify the top result against Google Flights (SerpApi). `false` (default): the check still runs automatically on a fresh search when the top isn't already a live price, within a client-aware time budget. `true`: force the check even on a cache hit. `full`: THOROUGH mode — force the same best-effort check with a longer ~35s budget (set it when you can wait, e.g. an autonomous agent). Always inspect `metadata.freshness`: if the live source is unavailable, fails, or reaches its spend cap, the response can still contain explicitly labeled cached indicators. No-op unless a SerpApi key is configured."New value: +"How hard to cross-check the top result's route, dates, and cabin against Google Flights (SerpApi). `false` (default): the check still runs automatically on a fresh search when the top isn't already a live price, within a client-aware time budget. `true`: force the check even on a cache hit. `full`: THOROUGH mode — force the same best-effort check with a longer ~35s budget (set it when you can wait, e.g. an autonomous agent). This does not verify the displayed airline, itinerary, gate, or booking URL; inspect `metadata.route_price_check` separately. Displayed Travelpayouts fares remain explicitly labeled cached indicators. No-op unless a SerpApi key is configured."

Previous value: -"Latest acceptable return date (ISO YYYY-MM-DD). Window from earliest must be ≤365 days. Required for a specific route; ignored in anywhere mode."New value: +"Latest acceptable return date for round-trip, or latest acceptable departure for one-way (ISO YYYY-MM-DD). Window from earliest must be ≤365 days. Required for a specific route; ignored in anywhere mode."

Previous value: -"Maximum trip duration in days (return - departure)."New value: +"Maximum round-trip duration in days (return - departure); ignored for one-way and anywhere mode."

Previous value: -"Minimum trip duration in days (return - departure)."New value: +"Minimum round-trip duration in days (return - departure); ignored for one-way and anywhere mode."

Previous value: -"Maximum number of results to return, sorted cheapest-first."New value: +"Maximum number of results to return, sorted cheapest-first. Specific routes allow up to 50; anywhere mode returns at most 12."

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

Previous value: -"Origin airport, 3-letter IATA code, UPPERCASE. Required for a specific route; with to=anywhere it may be omitted to auto-detect from the caller's IP country."New value: +"Origin airport, 3-letter IATA code, UPPERCASE. Required for every search, including to=anywhere."

Previous value: -"How hard to live-verify the top result against Google Flights (SerpApi). `false` (default): the check still runs automatically on a fresh search when the top isn't already a live price, within a client-aware time budget. `true`: force the check even on a cache hit. `full`: THOROUGH mode — wait for complete live verification and return the freshest prices with NO cached_indicators fallback (a longer ~35s budget; set it when you can wait, e.g. an autonomous agent). No-op unless a SerpApi key is configured."New value: +"How hard to live-verify the top result against Google Flights (SerpApi). `false` (default): the check still runs automatically on a fresh search when the top isn't already a live price, within a client-aware time budget. `true`: force the check even on a cache hit. `full`: THOROUGH mode — force the same best-effort check with a longer ~35s budget (set it when you can wait, e.g. an autonomous agent). Always inspect `metadata.freshness`: if the live source is unavailable, fails, or reaches its spend cap, the response can still contain explicitly labeled cached indicators. No-op unless a SerpApi key is configured."

Added value: +[
+  "from"
+]