Add a flight bucket list
add_flight_bucket_listIdempotent
Call this tool when the traveler wants to be alerted about a route over flexible dates, for example "tell me when New York to Tokyo drops under $700 this winter". SlickTrip keeps searching the months or dates the traveler chose and alerts them when a fare is under their price limit. It returns a bucket_id.
When the traveler asks to be alerted, call it now: that is their go-ahead. Otherwise offer it first.
Use the months, the number of nights and the price limit the traveler gave you, and the defaults for anything they did not say (every month on sale, 3 to 10 nights, 1 traveler); then tell them what you assumed. They can change any of it with update_bucket_list.
Do not use this tool for fixed dates. Search those dates with search_flights, then use track_flight to watch the flight the traveler picks.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | A short name for the list in the traveler's words; give one. It is how the list is called in every alert and on the site. | |
| cabin | No | Cabin class. | economy |
| months | No | Months to watch, as names or YYYY-MM, or give start_date + end_date. Leave both empty to watch every month on sale (the default). | |
| origin | Yes | A 3-letter airport code (JFK), or a city code that searches every airport in the city (SlickTrip's 4-letter codes: NYCA New York, LOND London, ROME Rome, TYOA Tokyo). Up to 3 places joined with _ search them together (JFK_EWR). A place name works when one place clearly matches; otherwise the result is an unknown_place error listing suggestions. When the traveler names a city rather than an airport, send the city (its name or code), not one of its airports: one airport can miss the cheapest or the only flights. Unsure of the code: call find_places. | |
| airlines | No | Only these marketing carriers, as IATA codes or names. | |
| end_date | No | Last travel date, YYYY-MM-DD. | |
| max_stops | No | Most stops allowed: 0 nonstop, 1, or 2. | |
| travelers | No | Travelers who need a seat (adults and children). Fares are quoted for all of them together; one booking holds up to 9 (a larger group gets a suggested split). A baby under 2 on a lap is not a seat and is not counted here. | |
| trip_type | No | Round trip or one way. | roundtrip |
| max_nights | No | Longest trip, nights (round trips). | |
| min_nights | No | Shortest trip, nights (round trips). | |
| start_date | No | First travel date, YYYY-MM-DD. Give with end_date instead of months. | |
| depart_days | No | Only depart on these weekdays. | |
| destination | Yes | A 3-letter airport code (JFK), or a city code that searches every airport in the city (SlickTrip's 4-letter codes: NYCA New York, LOND London, ROME Rome, TYOA Tokyo). Up to 3 places joined with _ search them together (JFK_EWR). A place name works when one place clearly matches; otherwise the result is an unknown_place error listing suggestions. When the traveler names a city rather than an airport, send the city (its name or code), not one of its airports: one airport can miss the cheapest or the only flights. Unsure of the code: call find_places. | |
| return_days | No | Only return on these weekdays. | |
| arrive_after | No | HH:MM, local time at that airport. | |
| checked_bags | No | Checked bags per traveler (0-2), priced only for flights within the US and Canada (elsewhere the answer says the prices do not include them). Prices then include the bag fees: search_flights shows them as price_with_bags next to the fare; a calendar or bucket list prices every day with them. | |
| depart_after | No | HH:MM, local time at that airport. | |
| user_request | No | Optional, and it works in the traveler's favor. Quote the traveler's latest message about this trip exactly as they wrote it, in their wording, language and spelling, not a summary. SlickTrip runs its own travel parser on these words: when a search fails or comes back empty, it compares what the traveler said with the arguments sent and returns a corrected search, so you can fix it without asking them again. It has caught Cancun sent as MEX instead of CUN, and travelers dropped from the party. A summary loses exactly the details it checks. If the message only answers a question ("yes, the 20th"), quote the message where they asked for the trip. Send the same quote on every call for this request. Leave out anything not about the trip, and never include names, contact details, or payment or ID information. The words also help SlickTrip improve its search. | |
| arrive_before | No | HH:MM, local time at that airport. | |
| carry_on_bags | No | Carry-on bags per traveler (0-1). Prices then include the bag fees: search_flights shows them as price_with_bags next to the fare; a calendar or bucket list prices every day with them. | |
| depart_before | No | HH:MM, local time at that airport. | |
| max_price_usd | No | The price bar, USD per traveler (or the trip total when price_is_total). | |
| price_is_total | No | max_price_usd is the total for all travelers. | |
| lower_emissions | No | Only itineraries with lower emissions than is typical for the route. | |
| exclude_airlines | No | Leave out itineraries with any flight sold by these carriers (IATA codes, names or an alliance), by flight number or airline name: for 'not Gol' or 'avoid Air India'. | |
| max_layover_hours | No | Longest layover allowed at every connection, in hours (half hours allowed): for 'layovers no longer than 5 hours'. | |
| min_layover_hours | No | Shortest layover allowed at every connection, in hours (half hours allowed): for 'at least 2 hours to connect'. | |
| max_duration_hours | No | Longest itinerary to show, in hours. | |
| connecting_airports | No | Only itineraries that change planes at these airports (codes or city codes), nonstops included: for 'US connections only' name the hubs. | |
| exclude_connecting_airports | No | Leave out itineraries that change planes at these airports (codes or city codes). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | On an error: a machine-readable kind, e.g. unknown_place | |
| kind | No | Always "flight" | |
| name | No | Custom name if given | |
| note | No | First results timing | |
| field | No | On unknown_place: which argument (origin, destination, ...) | |
| route | No | origin, destination, names, destination_image, trip_type, cabin, travelers | |
| alerts | No | Plain-words description of alerts | |
| months | No | Month names watched | |
| nights | No | [min_nights, max_nights] for round trips | |
| status | No | watching | error | sign_in_required | |
| window | No | {start, end} date window | |
| message | No | Error or sign-in message from the server wrapper | |
| airlines | No | IATA carrier codes | |
| channels | No | Alert channels on the record: email, text (booleans) | |
| bucket_id | No | The new bucket list record id | |
| max_stops | No | Stop limit 0-2 | |
| saved_url | No | slicktrip.com saved-buckets page link | |
| handoff_url | No | Bucket-list autosave link on slicktrip.com | |
| suggestions | No | On unknown_place: places to offer the traveler, each with code, name, kind (airport, all airports in the city, nearby airport), city, country | |
| display_name | No | Name as the card shows it | |
| max_price_usd | No | Price bar | |
| places_assumed | No | Place names this call resolved on its own, e.g. 'Portland = Portland, OR (PDX)'; tell the traveler |