Flight Search

Fetch live, bookable pricing for a specific route and date pair. Use it once the user has settled on exact travel dates, for example “Paris to New York departing June 1 returning June 8 in economy”. It also reprices an offer surfaced earlier by the calendar or destination tools so you can confirm availability before adding it to a trip.

Tool description (what the LLM sees)

Get live flight pricing and fare options. Provide exactly one of the "search" or "price_check" nested objects:

1. search: Live flight search by route and dates.
   Example: { "search": { "origin": "PAR", "destination": "NYC", "departure_date": "2027-06-01" } }
   Required fields: origin, destination, departure_date.
   Optional filters: return_date, trip_type, cabin_class, max_stops, multi_fare, max_price, limit, include_carriers, exclude_carriers, single_carrier_only, departure_time_range, arrival_time_range, return_departure_time_range, return_arrival_time_range, connection_time_min_minutes, connection_time_max_minutes, max_total_duration_minutes, refundable_only, changeable_only, checked_bag_included, via_airports, exclude_via_airports, aircraft_types, origin_alternate_airports, destination_alternate_airports, nearby_airports, same_connection_airport_only, same_origin_airport_only, same_turnaround_airport_only, origin_type, destination_type.
   DATE FLEXIBILITY: this call prices ONE exact date pair. Send "give or take a day", open windows and date ranges to flight_calendar instead. flight_calendar takes only direct_only, cabin_class, max_price and the time windows, refundable_only, changeable_only, checked_bag_included, max_stops and the carrier lists are NOT in its input. So when the user gave constraints like those, do not stop at the calendar result: once they pick dates there, call flight_search again on those exact dates WITH the original filters.

2. price_check: Get live pricing for a specific flight deal from discovery tools (flight_calendar, find_destination, flight_calendar).
   Example: { "price_check": { "offer_token": "token_from_discovery" } }

IMPORTANT: "search" and "price_check" are nested objects, not string values. Do NOT pass them as strings.

RESPONSE:
- Each flight includes detailed segments, fare options with baggage/refund/change rules, and a trip_item_token per fare. Every fare also carries refundable, changeable and checked_bag_included booleans.
- applied_filters lists the search filters this result set enforces; unapplied_filters lists the ones NO provider could enforce, each with a reason (and filters_notice spells the same thing out in one sentence). A filter in unapplied_filters still has to be applied by you, the flights were not narrowed by it. Both reports name a leg SIDE for the alternate-airport lists: an origin_alternate_airports / destination_alternate_airports list appears as "origin" / "destination".
- origin_alternate_airports / destination_alternate_airports take effect only against an AIRPORT anchor. Sent with a city anchor (origin_type / destination_type "city", or a code that resolves to a city) the search still runs and returns flights, the list is ignored, and the side comes back in unapplied_filters with the reason, that is a warning to relay, not an error.
- price_check may return status "flight_unavailable" with alternatives if the flight is no longer available, ask the user to choose.

NEXT STEP: Use the trip tool with add_item and the trip_item_token from the fare the user selects.

Flow: discovery (flight_calendar / find_destination / flight_calendar) or direct search → flight_search → trip → checkout

PASSENGERS: If a search fails, surface the error, never retry with a changed passenger list (e.g. dropping an infant); that silently changes the user's request.

PRICES: prices in the response are preformatted strings like USD 180.90, display them as-is; there are no minor-unit integers to convert.

Parameters

Name	Type	Required	Description
`search`	`object`	No	Live flight search by route and dates. Use city codes by default (PAR, NYC); use airport codes (CDG, JFK) only when the user specifies a particular airport. Takes ONE anchor departure_date (+ return_date for a round trip), no date ranges and no date arrays. Any date flexibility (“give or take a day”, open windows, an ask with no anchor date at all, or a range implying several candidate departure/return pairs) goes to flight_calendar instead.
`search.origin`	`string`	No	Origin IATA city code (e.g. PAR, NYC, LON) or airport code (e.g. CDG, JFK, LHR). City codes preferred, they search all airports in the city. ALWAYS convert place names to codes yourself before calling (Paris → PAR, Mexico City → MEX, Miami → MIA); a name like “Paris” fails validation. Required.
`search.origin_type`	`enum ("city" \| "airport")`	No	How to interpret origin: “city” searches all airports in the city; “airport” restricts to that specific airport. OMIT unless the user named a specific airport, when absent the code is resolved from the airport/city catalogue, which classifies it correctly on its own. Guessing “city” for an airport code (CDG, JFK) misreads the route.
`search.destination`	`string`	No	Destination IATA city code (e.g. MIL, BCN, TYO) or airport code (e.g. MXP, BCN, NRT). City codes preferred. ALWAYS convert place names to codes yourself before calling (Tokyo → TYO, São Paulo → SAO); a name like “Tokyo” fails validation. Required.
`search.destination_type`	`enum ("city" \| "airport")`	No	How to interpret destination: “city” searches all airports; “airport” restricts to that specific airport. OMIT unless the user named a specific airport, when absent the code is resolved from the airport/city catalogue.
`search.departure_date`	`string`	No	Single departure date (YYYY-MM-DD), no arrays or ranges. Required.
`search.return_date`	`string`	No	Single return date (YYYY-MM-DD) for a round trip. Omit for one-way.
`search.trip_type`	`enum ("oneway" \| "roundtrip")`	No	Optional. Derived from return_date when omitted.
`search.cabin_class`	`enum ("economy" \| "premium_economy" \| "business" \| "first")`	No	Preferred cabin. ADVISORY, not a filter: it is forwarded to the providers as a preference (Sabre CabinPref, TravelFusion TravelClass) and they may still return other cabins. It is NOT part of the applied/unapplied filter contract and never appears in `applied_filters`, read each fare’s own `cabin_class` to see what actually came back. Omit (default) for economy. Use when the user says “business class”, “first class”, etc.
`search.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”.
`search.multi_fare`	`boolean`	No	Defaults to TRUE: several branded fares per itinerary (the upsell ladder). Set false for a single fare per itinerary and much smaller responses.
`search.max_price`	`number`	No	Upper bound on the total fare for ALL passengers, in the requested currency. Use when the user gives a budget like “under $500”.
`search.limit`	`integer`	No	TOTAL number of flights returned (1-300). Caps the whole result set, not a per-page size; it only trims what comes back, since the providers still bound the real count.
`search.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.
`search.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.
`search.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.
`search.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”.
`search.departure_time_range.earliest`	`string`	No	Inclusive earliest local time-of-day (HH:MM, 24-hour).
`search.departure_time_range.latest`	`string`	No	Inclusive latest local time-of-day (HH:MM, 24-hour).
`search.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”.
`search.arrival_time_range.earliest`	`string`	No	Inclusive earliest local time-of-day (HH:MM, 24-hour).
`search.arrival_time_range.latest`	`string`	No	Inclusive latest local time-of-day (HH:MM, 24-hour).
`search.return_departure_time_range`	`object`	No	Round-trip only. Filter the RETURN leg by local departure time-of-day.
`search.return_departure_time_range.earliest`	`string`	No	Inclusive earliest local time-of-day (HH:MM, 24-hour).
`search.return_departure_time_range.latest`	`string`	No	Inclusive latest local time-of-day (HH:MM, 24-hour).
`search.return_arrival_time_range`	`object`	No	Round-trip only. Filter the RETURN leg by local arrival time-of-day.
`search.return_arrival_time_range.earliest`	`string`	No	Inclusive earliest local time-of-day (HH:MM, 24-hour).
`search.return_arrival_time_range.latest`	`string`	No	Inclusive latest local time-of-day (HH:MM, 24-hour).
`search.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.
`search.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).
`search.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.
`search.refundable_only`	`boolean`	No	Keep only fares that can be cancelled before departure (with or without a fee). Narrowing and conservative: fares whose rules cannot be verified are dropped, so some carriers disappear entirely. Each returned fare echoes the resolved `refundable` flag.
`search.changeable_only`	`boolean`	No	Keep only fares that allow a voluntary change (with or without a fee). Same conservative behavior as refundable_only. Each returned fare echoes the resolved `changeable` flag.
`search.checked_bag_included`	`boolean`	No	Keep only fares whose price already includes a checked bag. Use when the user says “with a bag included”, “I need to check luggage”.
`search.via_airports`	`array<string>`	No	Restrict connections to these IATA airport codes. Nonstop itineraries still pass. Example: [“CDG”,“AMS”]. At most 9 airports are honoured per leg (provider limit); a longer list comes back in unapplied_filters. Must not overlap exclude_via_airports.
`search.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.
`search.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.
`search.origin_alternate_airports`	`array<string>`	No	ADDITIONAL departure airports searched ALONGSIDE `origin`, e.g. [“EWR”,“LGA”] with `origin: "JFK"`. WIDENING ONLY, the anchor in `origin` is always searched. THE ANCHOR RANKS AND TRUNCATES the result set, so put the airport that matters most to the user in `origin`, not in this list: on one measured route, anchor JFK + alternate EWR came back 15 JFK / 35 EWR, while anchor EWR + alternate JFK came back 2 JFK / 48 EWR. TAKES EFFECT ONLY WITH AN AIRPORT ANCHOR, a city anchor (`origin_type: "city"`, or an `origin` that resolves to a city) already stands for its own airports, so the search still runs and returns results, this list is IGNORED, and it comes back in `unapplied_filters`. Not an error: read `unapplied_filters` and tell the user the list was not applied. On a round trip the whole side is mirrored, so these airports also apply to where the RETURN lands. Applied or not, the report names the SIDE, `origin`, never this field. Sabre honours the list; TravelFusion cannot (one station per leg) and reports it unapplied.
`search.destination_alternate_airports`	`array<string>`	No	ADDITIONAL arrival airports searched ALONGSIDE `destination`, e.g. [“EWR”,“LGA”] with `destination: "JFK"`. WIDENING ONLY, the anchor in `destination` is always searched. THE ANCHOR RANKS AND TRUNCATES the result set, so put the airport that matters most to the user in `destination`, not in this list: on one measured route, anchor JFK + alternate EWR came back 15 JFK / 35 EWR, while anchor EWR + alternate JFK came back 2 JFK / 48 EWR. TAKES EFFECT ONLY WITH AN AIRPORT ANCHOR, a city anchor (`destination_type: "city"`, or a `destination` that resolves to a city) already stands for its own airports, so the search still runs and returns results, this list is IGNORED, and it comes back in `unapplied_filters`. Not an error: read `unapplied_filters` and tell the user the list was not applied. On a round trip the whole side is mirrored, so these airports also apply to where the RETURN departs from. Applied or not, the report names the SIDE, `destination`, never this field. Sabre honours the list; TravelFusion cannot (one station per leg) and reports it unapplied.
`search.nearby_airports`	`boolean`	No	Ask the providers to also search alternate airports around each leg’s origin and destination. WIDENS the search. Use when the user says “or any nearby airport”.
`search.same_connection_airport_only`	`boolean`	No	Keep only itineraries whose connections arrive at and depart from the SAME airport (no cross-town airport change).
`search.same_origin_airport_only`	`boolean`	No	Round trips only: keep itineraries that return to the departure airport.
`search.same_turnaround_airport_only`	`boolean`	No	Round trips only: keep itineraries whose return departs from the airport the outbound arrived at.
`price_check`	`object`	No	Get live pricing for a specific flight deal. Returns confirmed fares with trip_item_token for booking. Accepts no search filters, the cached offer already has a concrete route, cabin, carrier, and price.
`price_check.offer_token`	`string`	Yes	offer_token from flight_calendar, find_destination, or flight_calendar results.
`passengers`	`object`	No	Passenger counts. Defaults to 1 adult.
`passengers.adults`	`integer`	No	Adult travelers (12+)
`passengers.children`	`integer`	No	Child travelers (2-11)
`passengers.infants`	`integer`	No	Infant travelers (under 2), traveling on an adult’s lap. Seated infants (own seat) are not supported.
`currency`	`string`	No	ISO 4217 currency code. Defaults to “USD”.
`locale`	`string`	No	BCP 47 locale. Defaults to “en-US”.
`user_intent`	`string`	No	The end user’s current request in their own words, e.g. “find a cheap flight to Tokyo in mid-June”. 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 and never changes the result of the call; Jinko uses it to understand demand and improve results.

Examples

Price-check a specific offer from discovery:

{
  "name": "flight_search",
  "arguments": {
    "price_check": {
      "offer_token": "offer_ABc123xYz..."
    }
  }
}

Live search by route (no prior discovery):

{
  "name": "flight_search",
  "arguments": {
    "search": {
      "origin": "PAR",
      "destination": "NYC",
      "departure_date": "2026-06-15",
      "return_date": "2026-06-22",
      "direct_only": false,
      "cabin_class": "economy"
    }
  }
}

Live search with passenger mix + max price filter:

{
  "name": "flight_search",
  "arguments": {
    "search": {
      "origin": "CDG",
      "destination": "JFK",
      "departure_date": "2026-07-01",
      "passengers": { "adults": 2, "children": 1 },
      "max_total": 1200,
      "direct_only": true
    }
  }
}

The response has detailed segment info per itinerary and multiple fare options per itinerary (economy / premium / business), each with a trip_item_token you pass to trip(add_item).

If price_check returns status: "flight_unavailable", the offer sold out, use the alternatives[] in the response or loop back to discovery.

Introduction

Flights

Hotels

Cart & Payment

Parameters

Examples

​Parameters

​Examples

Parameters

Examples