Flight award search is a preview. It is not yet stable, and its inputs and output may change.
It returns award prices only: it creates no offer, quote or booking, and results cannot be added
to a trip. Award fares carry no
trip_item_token. See
Flight award search.Tool description (what the LLM sees)
Tool description (what the LLM sees)
Award (miles / points) prices for one route and date pair, per airline loyalty program. Use it when the user asks what a flight costs in miles or points, which program has award seats, or how many miles a trip needs. Returns award prices only: it creates no offer, quote or booking, and results cannot be added to a trip. Preview: this tool is not yet stable, and its inputs and output may change.
INPUT
- Required: origin, destination, departure_date, trip_type (oneway or roundtrip). A roundtrip needs return_date; a oneway takes none of return_date, return_departure_time_range, return_arrival_time_range. origin and destination are 3-letter IATA airport codes (LHR, JFK): each search covers that one airport pair, so when the user names a city with several airports, search its main airport and call again for the others.
- programs: all 17 programs are queried by default. Send a list only when the user named programs (codes in the field description).
- cabin_class: omit it for every cabin. adults (1-9) counts travellers: only flights with that many award seats in one cabin are returned.
- Award filters: max_miles (per person; on a round trip, outbound + return), saver_only, max_mixed_cabin_share, sort (miles, departure, duration), limit (1-100, default 20).
- flight_search filters under the same names: max_stops, include_carriers, exclude_carriers, single_carrier_only, via_airports, exclude_via_airports, aircraft_types, departure_time_range, arrival_time_range, connection_time_min_minutes, connection_time_max_minutes, max_total_duration_minutes, same_connection_airport_only, and on a roundtrip return_departure_time_range, return_arrival_time_range. Every filter that narrows the results is applied as sent.
- Not accepted: max_price (send max_miles), multi_fare, refundable_only, changeable_only, checked_bag_included (award results carry no fare rules or baggage terms), currency (taxes come in each program's own currency), legs (one origin and destination only), passengers, children, infants (send adults), direct_only (send max_stops 0), origin_type, destination_type, origin_alternate_airports, destination_alternate_airports, nearby_airports, same_origin_airport_only, same_turnaround_airport_only (one airport pair per search).
RESPONSE
- When a program's prices are being refreshed the answer can come back with status "partial", meaning some loyalty programs were still being checked: call again to get their prices.
- Miles and points of different programs are different currencies: give each program's price on its own and do not call one program cheaper than another by comparing their numbers.
- The text has one line per flight: flight numbers, local times, stops, then each program's lowest miles + taxes with its cabin and seats.
- structuredContent carries the full payload: every fare per program and cabin, per-direction prices on a round trip, seats and the saver flag.
- No fare has a trip_item_token. For a cash ticket use flight_search; an award ticket is booked with the loyalty program.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
origin | string | Yes | Departure airport (3-letter IATA airport code). An IATA airport code: each search covers the one origin-destination airport pair, so search other airports separately. |
destination | string | Yes | Arrival airport (3-letter IATA airport code). An IATA airport code: each search covers the one origin-destination airport pair, so search other airports separately. |
departure_date | string | Yes | Single departure date (YYYY-MM-DD), no arrays or ranges. Required. |
trip_type | enum ("oneway" | "roundtrip") | Yes | Required: oneway or roundtrip. A roundtrip needs return_date. A oneway takes none of return_date, return_departure_time_range, return_arrival_time_range. |
return_date | string | null | No | Return date (YYYY-MM-DD). Required when trip_type is roundtrip; omit it, or send null, on a oneway. |
max_stops | integer | No | Maximum stops per leg (0-2). 0 = nonstop, send max_stops: 0 when the user says “direct only” / “non-stop” / “no layovers”; 1 when the user says “at most one stop”. |
include_carriers | array<string> | No | IATA 2-letter marketing carrier codes to include (whitelist). Example: [“AF”,“KL”]. ALWAYS convert airline names to codes yourself (Air France → AF, Delta → DL); a name like “Delta” fails validation. A brand that operates several marketing carriers needs every code listed (easyJet → U2, EC, DS). Use when the user says “Air France only”, “fly Delta”, etc. Must not overlap exclude_carriers. Matching means EVERY segment is marketed by a listed carrier (codeshares count by marketing carrier). When nothing matches, the search returns no offers with reason no_matches; the platform never widens to other carriers. Tell the user no itinerary satisfied the airline filter and ask which filter to relax. |
exclude_carriers | array<string> | No | IATA 2-letter marketing carrier codes to exclude (blacklist). Example: [“FR”,“U2”]. ALWAYS convert airline names to codes yourself (Ryanair → FR, Frontier → F9); a name like “Ryanair” fails validation. A brand that operates several marketing carriers needs every code listed (“no Wizz Air” → W6, W9). Use when the user says “no Ryanair”, “avoid budget airlines”, etc. Must not overlap include_carriers. |
single_carrier_only | boolean | No | Keep only itineraries marketed by ONE carrier end to end. Use when the user says “same airline the whole way” or wants to avoid split-carrier connections. |
departure_time_range | object | No | Filter the OUTBOUND leg by local departure time-of-day. Example: { “earliest”: “08:00”, “latest”: “12:00” }. Use when the user says “morning flight”, “leave after 6pm”. |
departure_time_range.earliest | string | No | Inclusive earliest local time-of-day (HH:MM, 24-hour). |
departure_time_range.latest | string | No | Inclusive latest local time-of-day (HH:MM, 24-hour). |
arrival_time_range | object | No | Filter the OUTBOUND leg by local arrival time-of-day. Example: { “latest”: “20:00” }. Use when the user says “arrive before dinner”, “land by noon”. |
arrival_time_range.earliest | string | No | Inclusive earliest local time-of-day (HH:MM, 24-hour). |
arrival_time_range.latest | string | No | Inclusive latest local time-of-day (HH:MM, 24-hour). |
connection_time_min_minutes | integer | No | Minimum layover length, in minutes, for EVERY connection of EVERY leg. Use when the user wants a comfortable connection (“at least 90 minutes to change planes”). Must not exceed connection_time_max_minutes. |
connection_time_max_minutes | integer | No | Maximum layover length, in minutes, for EVERY connection of EVERY leg. Use when the user says “no long layovers” (“under 3 hours” → 180). |
max_total_duration_minutes | integer | No | Cap on EACH leg’s total elapsed travel time, in minutes (gate to gate, layovers included). Use when the user says “nothing longer than 12 hours” → 720. |
via_airports | array<string> | No | Restrict connections to these IATA airport codes. Nonstop itineraries still pass. Example: [“CDG”,“AMS”]. Every connection in a returned itinerary is at a listed airport; sources search at most 9 per leg. Must not overlap exclude_via_airports. |
exclude_via_airports | array<string> | No | Ban connections at these IATA airport codes. Example: [“LHR”] when the user says “anything but Heathrow”. Lists longer than 9 are still fully enforced. Must not overlap via_airports. |
aircraft_types | array<string> | No | Restrict every segment to these IATA aircraft equipment codes. Example: [“320”,“321”]. Use only when the user names equipment; most users do not. |
same_connection_airport_only | boolean | No | Keep only itineraries whose connections arrive at and depart from the SAME airport (no cross-town airport change). |
return_departure_time_range | object | null | No | Roundtrip only: filter the RETURN leg by local departure time-of-day. Omit it, or send null, on a oneway. |
return_arrival_time_range | object | null | No | Roundtrip only: filter the RETURN leg by local arrival time-of-day. Omit it, or send null, on a oneway. |
cabin_class | enum ("economy" | "premium_economy" | "business" | "first") | null | No | Cabin to price. Omit it, or send null, to get every cabin; send a cabin only when the user asked for one. With a cabin, both directions of a round trip are priced in that cabin. |
adults | integer | No | Number of travellers (1-9). A flight is returned only when at least this many award seats are open in the same cabin. Miles and taxes are always per person. Children and infants are not priced separately. |
limit | integer | No | Number of flights returned (1-100, default 20). The result’s total says how many flights matched. |
programs | array<enum ("aadvantage" | "atmos_rewards" | "skymiles" | "flying_blue" | "flying_club" | "trueblue" | "qantas_frequent_flyer" | "eurobonus" | "miles_and_smiles" | "mileageplus" | "velocity" | "etihad_guest" | "finnair_plus" | "aeromexico_rewards" | "azul_fidelidade" | "smiles_br" | "smiles_ar")> | null | No | Loyalty programs to price, by code. Omit it, or send null, to query all 17: aadvantage (American AAdvantage), atmos_rewards (Atmos Rewards, Alaska and Hawaiian), skymiles (Delta SkyMiles), flying_blue (Flying Blue, Air France-KLM), flying_club (Virgin Atlantic Flying Club), trueblue (JetBlue TrueBlue), qantas_frequent_flyer (Qantas Frequent Flyer), eurobonus (SAS EuroBonus), miles_and_smiles (Turkish Airlines Miles&Smiles), mileageplus (United MileagePlus), velocity (Virgin Australia Velocity), etihad_guest (Etihad Guest), finnair_plus (Finnair Plus), aeromexico_rewards (Aeromexico Rewards), azul_fidelidade (Azul Fidelidade), smiles_br (GOL Smiles Brazil), smiles_ar (GOL Smiles Argentina). Send a list only when the user named programs, for example the ones they hold miles in. |
max_miles | integer | null | No | Most miles per person, in the requested cabin. On a round trip it caps outbound + return together. Omit it, or send null, for no cap. |
saver_only | boolean | No | Keep only saver-level award fares. Programs that have no saver level are not affected. |
max_mixed_cabin_share | number | null | No | Largest share of flight time (0 to 1) allowed in a cabin lower than cabin_class, e.g. 0.25. 0 keeps only fares in the requested cabin from end to end. Omit it, or send null, unless the user cares about mixed cabins. |
sort | enum ("miles" | "departure" | "duration") | No | Order of the flights: miles (fewest miles first, the default), departure (earliest first) or duration (shortest first). |
user_intent | string | No | The end user’s current request in their own words, e.g. “help me with my travel plans”. Pass it as-is when short; otherwise condense the goal and constraints into 1-2 sentences. Strip personal identifiers (names, emails, phone numbers, addresses, payment details), replace them with placeholders like “[name]”. Optional. Jinko uses it to understand demand, and hotel_search uses it to rank hotel results against what the user asked for (e.g. “quiet, with a gym, near Times Square”), so keep the user’s stated preferences in it. |