Flight Search

Cabin class and empty live searches

For search, omit cabin_class or send null when the user has not chosen a cabin. Providers search economy by default, and other recognized cabins can still be returned. Send an explicit cabin only when the user requests it: fares must match on the longest segment, while shorter connections may use another cabin. When the live search finds no matching offers, the tool returns a successful result with status: "empty", reason: "no_matches", and an instruction to explain the outcome: it asks the user which filter to relax when the search sent a narrowing filter, and otherwise whether to try other dates or airports. Do not silently change the cabin or other filters. This holds even when one airline source could not be searched, as long as another answered; results do not say which sources failed. A search where every source failed returns an error result with retry guidance and one of the fixed messages listed in Messages on supplier failures; preserve the filters when retrying later. These rules apply to search. price_check and cache-based discovery keep their existing behavior. 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. Set the unused one to null or leave it out; for a route search, send "price_check": null.

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.
   ROUTE CODES: the city code when the user named a city (PAR, NYC), the airport code when they named an airport (CDG, JFK). Untyped, a code that names a multi-airport city is searched as the city and any other code as the airport. LAX, MIA and LAS are both a city code and that city's main airport, so untyped LAX is the Los Angeles CITY and the provider returns other Los Angeles airports too (Ontario, ONT, often cheapest). When the user said "LAX", send destination_type: "airport".
   Optional filters: return_date, trip_type, cabin_class, max_stops, multi_fare, max_total (whole-trip budget for all travelers), 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_total 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. The calendar's (and find_destination's) max_total caps a cached fare, and cached fares are priced for one adult; a whole-party budget is divided by adults only for a loose pre-filter there. This tool's max_total covers the whole trip for all travelers, send the user's whole-trip figure unchanged, or for a per-person figure multiply by the number of travelers. Do not carry the calendar figure across unchanged for a party of several.

2. price_check: Get live pricing for a specific flight deal. In structuredContent, use flights[].offer_token from flight_calendar or find_dates, destinations[].offer_token from find_destination, or flight.offer_token from price_monitoring as price_check.offer_token.
   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:
- The text result is a summary, not JSON: the itinerary count, carriers, stops and price range, then each itinerary's legs (local times, durations, stopovers) and one line per fare ending in trip_item_token=<token>, with that fare's price, refund, change and checked-bag terms on the same line. Every bookable token is listed.
- structuredContent carries the full payload: every flight with detailed segments and 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.
- FILTERS: Every filter that narrows the results (cabin on the longest segment, stops, price, airlines, times, connections, fare conditions, aircraft) is applied exactly as sent: no returned itinerary breaks one. Options that widen a search (alternate or nearby airports) are searched where the source supports them, and sources search at most 9 via_airports per leg. An empty result carries an instruction: relay it. It asks which filter to relax only when a narrowing filter was sent; otherwise it asks about other dates or airports.
- origin_alternate_airports / destination_alternate_airports are searched beside an airport or a city anchor: origin NYC with ["BOS"] covers New York's airports and Boston.
- price_check may return status "offer_unavailable" when the selected offer no longer matches, including its cabin. The same flight may still have other fares. Show any returned alternatives and ask the user to choose; do not book the original offer.

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) or price_monitoring 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: total_price is for all travellers; price_per_person is per person.

Parameters

Name	Type	Required	Description
`search`	`object \| null`	No	Live flight search by route and dates. Use city codes when the user named a city (PAR, NYC) and airport codes when they named an airport (CDG, JFK). A code a city shares with its main airport (LAX, MIA, LAS) is read as the CITY unless you send origin_type / destination_type “airport”, send it when the user said “LAX”, since the city search returns other Los Angeles airports such as Ontario (ONT). 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.
`price_check`	`object \| null`	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.
`traveler_counts`	`object`	No	How many travelers of each type. Defaults to 1 adult.
`traveler_counts.adults`	`integer`	No	Adult travelers (12+)
`traveler_counts.children`	`integer`	No	Child travelers (2-11)
`traveler_counts.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. “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.

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": "2027-06-15",
      "return_date": "2027-06-22",
      "cabin_class": "economy"
    }
  }
}

Live search with passenger mix + max price filter:

{
  "name": "flight_search",
  "arguments": {
    "search": {
      "origin": "CDG",
      "destination": "JFK",
      "departure_date": "2027-07-01",
      "max_total": 1200,
      "max_stops": 0
    },
    "traveler_counts": { "adults": 2, "children": 1 }
  }
}

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: "offer_unavailable", the selected offer no longer matches. Search again and ask the user to choose an available live fare.

Introduction

Flights

Hotels

Cars

Trip & Payment

Marketing claim

Cabin class and empty live searches

Parameters

Examples

​Cabin class and empty live searches

​Parameters

​Examples

Cabin class and empty live searches

Parameters

Examples