Search flights
search_flightsFull Description
Use this to search flights between cities and show them as a horizontal carousel widget. Supports one-way, round-trip (flat fields), and multi-city/open-jaw (itinerary array). Call this tool at most once per user request.
Parameters (2 required, 12 optional)
countrystringISO 3166-1 alpha-2 country code used as booking market. IMPORTANT: Infer it from the trip ORIGIN (not destination). Examples: Amsterdam/AMS -> NL, Oslo/OSL -> NO. Always uppercase, 2 letters.
travellersstringPassenger specification. Adults only: plain number (e.g. '2') or 'adt:N'. Mixed groups: comma-separated segments where 'adt:N' = N adults, 'chd:AGE' = one child aged AGE (2–17), 'inf:AGE' = one infant aged AGE (0–1). Example: 'adt:2,chd:7,chd:4,inf:1' for 2 adults + child aged 7 + child aged 4 + infant aged 1. If unspecified, default to 1 adult. Limits: maximum 9 travellers total; at least 1 adult required per infant.
allowedCarriersarrayOptional list of 2-letter IATA carrier codes to include (e.g. ['LH', 'BA']). Use this if the user asks to include specific airlines like Lufthansa or SAS. When specified, only trips flown in part or in whole by one of these carriers are returned. Filtering is applied API-side before any excludedCarriers client-side filtering.
cabinstringCabin class code. Y = Economy (default), S = Premium Economy, C = Business, J = Premium Business, F = First, P = Premium First. If not specified, defaults to Economy. NOTE: Higher cabin classes may return some results at a lower cabin class when certain segments do not offer the requested class.
CFJPSYdepartureDatestringOutbound date in YYYY-MM-DD format. Validation: Date must be between [Today] and [Today + 360 Days]. On failure: Politely explain the limit and ask for a new date
destinationstringThe 3-letter IATA code for the destination city or airport. IMPORTANT: You MUST resolve user input (e.g., 'London') to its IATA code (e.g., 'LHR').If it is a city with multiple airports, return the city code (for example, London -> LON).
excludedCarriersarrayOptional list of 2-letter IATA carrier codes to exclude (e.g. ['FR', 'RK']). Use this if the user asks to exclude specific airlines like Ryanair. Filtering is applied client-side after the API response (after any allowedCarriers filtering).
itineraryarrayMulti-city / open-jaw itinerary. An array of leg objects, each with origin, destination, and departureDate. When present, overrides the flat origin/destination/departureDate fields. Max 6 legs. Dates must be in chronological order.
maxresultintegerMaximum number of flight options to return (1–5)
5onlyDirectFlightsbooleanIf true, only direct (non-stop) flights are returned. Defaults to false.
originstringThe 3-letter IATA code for the origin city or airport. IMPORTANT: You MUST resolve user input (e.g., 'Stockholm') to its IATA code (e.g., 'STO').If it is a city with multiple airports, return the city code (for example, London -> LON).
resolvedAirlineNamesobjectA mapping from 2-letter IATA carrier codes to their full airline names. You SHOULD populate this with the names of airlines likely to operate the flights (or all known airlines for the requested route) so the UI can display them. Example: {"FR": "Ryanair", "SK": "SAS", "BA": "British Airways"}.
resolvedIataNamesobjectA mapping from 3-letter IATA airport codes to their full airport names. You SHOULD populate this with the origin, destination, and likely connection airports. Example: {"LHR": "London Heathrow", "ARN": "Stockholm Arlanda"}.
returnDatestringOptional return date in YYYY-MM-DD format. Validation: Date must be between [Today] and [Today + 360 Days]. On failure: Politely explain the limit and ask for a new date