search_flights
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". This is the flexible-date search the big flight tools (Google Flights, Kayak, Skyscanner, Kiwi) keep behind their consumer UI and don't expose via API. Pass origin/destination as IATA codes, 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). Supports cabin class: pass cabin=business (or premium_economy/first) to find business-class deals — the verdict then judges the fare against that cabin's OWN typical prices, and metadata.deal_signal flags a business fare below its typical band. 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 get live-verified prices. If you can wait ~30s for the freshest fully-verified prices (e.g. you're an autonomous agent), set verify=full — the top result is then live-verified with no cached_indicators fallback.
Parameters13
| from | string | optional | 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. |
| to | string | optional | Destination airport, 3-letter IATA code, UPPERCASE. Pass `anywhere` (or omit) to get the cheapest destinations from the origin instead of a specific route. |
| earliest | string | optional | Earliest acceptable departure date (ISO YYYY-MM-DD). Required for a specific route; ignored in anywhere mode. |
| latest | string | optional | Latest acceptable return date (ISO YYYY-MM-DD). Window from earliest must be ≤365 days. Required for a specific route; ignored in anywhere mode. |
| min_days | integer | optional | Minimum trip duration in days (return - departure). |
| max_days | integer | optional | Maximum trip duration in days (return - departure). |
| one_way | boolean | optional | If true, search one-way flights; return_date and duration_days will be null. |
| top_n | integer | optional | Maximum number of results to return, sorted cheapest-first. |
| currency | string | optional | Result currency, 3-letter ISO code UPPERCASE. |
| max_transfers | integer | optional | Maximum number of transfers/layovers per leg. 0 = nonstop only, 1 = up to 1 stop, etc. Omit for no filter. |
| cabin | string | optional | 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. |
| verify | string | optional | 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. |
| ch | string | optional | 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. |
Raw schema
{
"type": "object",
"properties": {
"from": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "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.",
"examples": [
"SGN",
"HKG",
"BKK"
],
"title": "from",
"type": "string"
},
"to": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Destination airport, 3-letter IATA code, UPPERCASE. Pass `anywhere` (or omit) to get the cheapest destinations from the origin instead of a specific route.",
"examples": [
"ICN",
"NRT",
"SIN",
"anywhere"
],
"title": "to",
"type": "string"
},
"earliest": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
],
"description": "Earliest acceptable departure date (ISO YYYY-MM-DD). Required for a specific route; ignored in anywhere mode.",
"examples": [
"2026-06-01"
],
"title": "earliest",
"type": "string"
},
"latest": {
"anyOf": [
{
"type": "string",
"format": "date"
},
{
"type": "null"
}
],
"description": "Latest acceptable return date (ISO YYYY-MM-DD). Window from earliest must be ≤365 days. Required for a specific route; ignored in anywhere mode.",
"examples": [
"2026-08-31"
],
"title": "latest",
"type": "string"
},
"min_days": {
"type": "integer",
"maximum": 365,
"minimum": 1,
"description": "Minimum trip duration in days (return - departure).",
"examples": [
10
],
"default": 3,
"title": "min_days"
},
"max_days": {
"type": "integer",
"maximum": 365,
"minimum": 1,
"description": "Maximum trip duration in days (return - departure).",
"examples": [
15
],
"default": 30,
"title": "max_days"
},
"one_way": {
"type": "boolean",
"description": "If true, search one-way flights; return_date and duration_days will be null.",
"default": false,
"title": "one_way"
},
"top_n": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "Maximum number of results to return, sorted cheapest-first.",
"examples": [
10
],
"default": 10,
"title": "top_n"
},
"currency": {
"type": "string",
"description": "Result currency, 3-letter ISO code UPPERCASE.",
"examples": [
"USD",
"EUR",
"SGD"
],
"default": "USD",
"title": "currency"
},
"max_transfers": {
"anyOf": [
{
"type": "integer",
"maximum": 5,
"minimum": 0
},
{
"type": "null"
}
],
"description": "Maximum number of transfers/layovers per leg. 0 = nonstop only, 1 = up to 1 stop, etc. Omit for no filter.",
"examples": [
0,
1
],
"title": "max_transfers",
"type": "integer"
},
"cabin": {
"type": "string",
"description": "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.",
"examples": [
"economy",
"business"
],
"default": "economy",
"title": "cabin"
},
"verify": {
"type": "string",
"description": "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.",
"examples": [
"false",
"true",
"full"
],
"default": "false",
"title": "verify"
},
"ch": {
"type": "string",
"maxLength": 64,
"description": "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.",
"examples": [
"web",
"mcp",
"direct"
],
"default": "direct",
"title": "ch"
}
},
"title": "search_flightsArguments"
}