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.
Booking: after showing flights, offer the person a booking link for the one they like. When they pick a flight or fare, say they want to book, or ask how to book, call create_booking_intent with that flight from these results (with the chosen fare) — searching again is not needed to book, and the website re-checks the price at checkout.
View input schema
{
"type": "object",
"properties": {
"origin": {
"type": "string",
"description": "IATA origin airport code (e.g., 'MIA', 'JFK', 'LAX')"
},
"destination": {
"type": "string",
"description": "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."
},
"departure_date": {
"type": "string",
"description": "Departure date (YYYY-MM-DD)"
},
"return_date": {
"type": "string",
"description": "Return date for round-trip (YYYY-MM-DD). Omit for one-way."
},
"passengers": {
"type": "number",
"description": "Total travelers (1-9, default: 1). With adults/children_ages/infants_on_lap, this is worked out for you."
},
"adults": {
"type": "integer",
"minimum": 1,
"maximum": 9,
"description": "Adults travelling (1-9). When given it is authoritative; children and lap infants are counted separately."
},
"children_ages": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 17
},
"description": "One age (0-17) per child with their OWN seat, as of the last flight of the trip."
},
"infants_on_lap": {
"type": "integer",
"minimum": 0,
"maximum": 9,
"description": "Under-2s travelling on an adult's lap (no seat). At most one per adult."
},
"cabin_class": {
"type": "string",
"enum": [
"economy",
"premium_economy",
"business",
"first"
],
"description": "Cabin class (default: economy)"
},
"max_price_usd": {
"type": "number",
"description": "Maximum total price in USD"
},
"nonstop_only": {
"type": "boolean",
"description": "Only show nonstop flights (default: false)"
},
"place": {
"type": "object",
"description": "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.",
"properties": {
"city": {
"type": "string"
},
"region": {
"type": "string",
"description": "State or region, or empty."
},
"country": {
"type": "string",
"description": "ISO 3166-1 alpha-2 code (territories use their own, e.g. PR)."
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"airports": {
"type": "array",
"items": {
"type": "string"
},
"description": "IATA codes of the airports serving the place."
},
"label": {
"type": "string",
"description": "How to name the place to the person, e.g. 'Birmingham, GB'."
},
"kind": {
"type": "string",
"enum": [
"city",
"town",
"region",
"island"
],
"description": "What the place is, as a search returned it. Pass it back unchanged: a town, region or island has its hotels searched around it."
},
"radius_km": {
"type": "number",
"description": "The hotel search radius for this place, as a search returned it."
},
"arrival_airports": {
"type": "array",
"description": "The airports to fly this place by, best first, as a search returned them. Pass them back unchanged.",
"items": {
"type": "object",
"properties": {
"iata": {
"type": "string"
}
},
"required": [
"iata"
]
}
},
"gateway_airport": {
"type": "string",
"description": "The one airport a wide search flies this place by, as a search returned it."
},
"extent_km": {
"type": "number",
"description": "The size of a region or island, as a search returned it."
}
},
"required": [
"country",
"latitude",
"longitude"
]
},
"origin_place": {
"type": "object",
"description": "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.",
"properties": {
"city": {
"type": "string"
},
"region": {
"type": "string",
"description": "State or region, or empty."
},
"country": {
"type": "string",
"description": "ISO 3166-1 alpha-2 code (territories use their own, e.g. PR)."
},
"latitude": {
"type": "number"
},
"longitude": {
"type": "number"
},
"airports": {
"type": "array",
"items": {
"type": "string"
},
"description": "IATA codes of the airports serving the place."
},
"label": {
"type": "string",
"description": "How to name the place to the person, e.g. 'Birmingham, GB'."
},
"kind": {
"type": "string",
"enum": [
"city",
"town",
"region",
"island"
],
"description": "What the place is, as a search returned it. Pass it back unchanged: a town, region or island has its hotels searched around it."
},
"radius_km": {
"type": "number",
"description": "The hotel search radius for this place, as a search returned it."
},
"arrival_airports": {
"type": "array",
"description": "The airports to fly this place by, best first, as a search returned them. Pass them back unchanged.",
"items": {
"type": "object",
"properties": {
"iata": {
"type": "string"
}
},
"required": [
"iata"
]
}
},
"gateway_airport": {
"type": "string",
"description": "The one airport a wide search flies this place by, as a search returned it."
},
"extent_km": {
"type": "number",
"description": "The size of a region or island, as a search returned it."
}
},
"required": [
"country",
"latitude",
"longitude"
]
}
},
"required": [
"origin",
"destination",
"departure_date"
]
}