search_flights
Searches flights between two airports (IATA codes such as JFK or LHR) on a departure date, with an optional return date, cabin class, travelers, maximum price and nonstop filter. Results come from our flight partner's airline inventory and include the airline, flight numbers, times, stops, duration, fare, baggage and refundability. Each result is ONE itinerary (the same flights at the same times) with its fare_options, cheapest first: each has its own offer_id, fare brand (e.g. Basic Economy, Main Cabin, Business), cabin, price_usd, rule (changes and refund in a few words), bags (the bags included with that fare, in words to repeat as given: a basic fare often has none, and not provided by the airline means unknown, not none), dot_24h_refund_eligible (true = the US DOT 24-hour rule covers that fare: the traveler can cancel within 24 hours of booking for a full refund; say so only when it is true), changeable/refundable and, when stated, change_penalty_usd and refund_penalty_usd (the AIRLINE's penalties: what the traveler loses to the airline on a change or a refund). Those are the airline's terms only: Autonomad's own change and cancellation fees come on top and are stated on the booking page and in create_booking_intent's flight_money_terms, so never call a fare free to change or free to cancel. When the cheapest fare is Basic Economy (is_basic_economy), say so plainly and repeat its terms exactly as returned (its rule, fare_note and fare_warning): Basic Economy fares differ by airline, so never describe one's changes or refunds in any other words. Offer the other fares and let the person choose. Searching does not reserve anything or charge anyone.
Travelers can be any age: only the account holder who books and pays must be 18 or older. For a party with children, send adults, children_ages (one age 0-17 per child who has their own seat, as of the last flight of the trip) and infants_on_lap (under-2s on an adult's lap, at most one per adult); at most 9 travelers in total. With any child or lap infant in the search, each offer's price_usd is the total for every traveler and there is no per-person price: quote the total, never divide it.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| place | No | The exact place of this trip stop: the `place` an earlier search for the trip returned, or the candidate the person picked when a search asked which place they meant. Searches given the same place cover the same place. For flights it is the destination, flown by its main airport. | |
| adults | No | Adults travelling (1-9). When given it is authoritative; children and lap infants are counted separately. | |
| origin | Yes | IATA origin airport code (e.g., 'MIA', 'JFK', 'LAX') | |
| passengers | No | Total travelers (1-9, default: 1). With adults/children_ages/infants_on_lap, this is worked out for you. | |
| cabin_class | No | Cabin class (default: economy) | |
| destination | Yes | Where the person is flying to: a place name (e.g. 'Napa', 'Aspen', 'Bora Bora') or an IATA airport code in capitals (e.g. 'OAK'). A name is flown as that place: for a town, region or island the airports near it are compared (meta.arrival_airports, with the drive from each) and each offer says which one it lands at. A code is flown to that airport only. | |
| return_date | No | Return date for round-trip (YYYY-MM-DD). Omit for one-way. | |
| nonstop_only | No | Only show nonstop flights (default: false) | |
| origin_place | No | The exact place the trip starts from, as an earlier search returned it (`origin_place`) or as the person picked it from a list of candidates. | |
| children_ages | No | One age (0-17) per child with their OWN seat, as of the last flight of the trip. | |
| max_price_usd | No | Maximum total price in USD | |
| departure_date | Yes | Departure date (YYYY-MM-DD) | |
| infants_on_lap | No | Under-2s travelling on an adult's lap (no seat). At most one per adult. |