Get live flight pricing — search by route, or re-price a known offer

3-letter IATA city or airport code. See origin_type for how an untyped code is read. origin and destination must differ. A 3-letter code the platform’s location catalog does not recognise is not refused: it is searched as an airport, and if no provider sells it the search answers result: no_matches.

3-letter IATA city or airport code. See destination_type for how an untyped code is read: LAX alone is the Los Angeles CITY; send destination_type: "airport" for the airport only. origin and destination must differ. A 3-letter code the platform’s location catalog does not recognise is not refused: it is searched as an airport, and if no provider sells it the search answers result: no_matches.

How to read the code: city searches every airport of the city, airport only that one airport. Omit it and the platform applies one rule: a code that names a multi-airport city is searched as the city; every other code is searched as the airport. Untyped NYC, LON or PAR is the city; untyped JFK, LHR or CDG is the airport; and untyped LAX, MIA or LAS — codes a city shares with its main airport — is the CITY, so results can land at any airport of that city. If the user named the airport, send airport; if they named the city, omit the field. The provider decides which airports a city holds, so a city search can return airports the catalog does not list under that code: searched as a city, LAX returns Ontario (ONT) fares, often as the cheapest offers. Each offer’s legs carry the airports flown; the offer-level origin / destination carry the city.

How to read the code: city searches every airport of the city, airport only that one airport. Omit it and the platform applies one rule: a code that names a multi-airport city is searched as the city; every other code is searched as the airport. Untyped NYC, LON or PAR is the city; untyped JFK, LHR or CDG is the airport; and untyped LAX, MIA or LAS — codes a city shares with its main airport — is the CITY, so results can land at any airport of that city. If the user named the airport, send airport; if they named the city, omit the field. The provider decides which airports a city holds, so a city search can return airports the catalog does not list under that code: searched as a city, LAX returns Ontario (ONT) fares, often as the cheapest offers. Each offer’s legs carry the airports flown; the offer-level origin / destination carry the city.

Departure date, YYYY-MM-DD: the local date at origin. Required in search mode, with origin and destination; not allowed beside offer_token. A date that does not exist on the calendar (2026-02-30) is refused with 422 naming the field.

Return date, YYYY-MM-DD, on or after departure_date (a same-day return is valid). Sending it makes the search a round trip; see trip_type.

oneway or roundtrip. Omit it and return_date decides: present is a round trip, absent a one-way trip. roundtrip requires return_date, and oneway refuses it (422 naming return_date).

Omit this field or send null to let the provider default the search to economy without applying a cabin filter. Send an explicit enum value to require each fare’s representative cabin to equal it. The representative cabin is the cabin on the longest flight segment; shorter connecting segments may use another cabin. An omitted or null cabin applies no cabin filter.

DEPRECATED — send max_stops: 0 instead. Still accepted: direct_only is folded into max_stops (true becomes max_stops: 0) before the search runs, so only max_stops reaches the platform. Setting it beside a non-zero max_stops is rejected.

Maximum stops per leg: 0 non-stop (the way to ask for direct flights), 1 one connection, 2 two. Applies to every leg of the trip.

Branded fare ladder: several fares per itinerary (upsell options). Defaults to true when omitted; send false for a single fare per itinerary and a smaller response. An offer carries at most 10 fares, the cheapest fare of each cabin kept first; a provider that sells no fare ladder returns a single fare either way.

Drop fares whose total price (all passengers) exceeds this cap, in currency, major units. A fare priced in another currency is usually converted to currency with the platform’s FX rate before the comparison, but not always: a provider whose first priced offer is already in currency drops its offers in other currencies as unverifiable instead of converting them. A fare whose currency cannot be converted is not returned.

Shortest acceptable layover, in minutes, applied to every connection of every leg. Must not exceed connection_time_max_minutes. Conservative, like refundable_only: an itinerary with a connection whose times are unknown cannot be checked and is dropped.

Longest acceptable layover, in minutes, applied to every connection of every leg. Conservative in the same way as connection_time_min_minutes: a connection whose times are unknown drops the itinerary.

Cap each leg’s door-to-door elapsed travel time, in minutes.

Keep only fares that can be cancelled before departure (with or without a fee). Conservative: a fare whose rules the platform cannot verify is DROPPED, so carriers that publish no rule data disappear under this filter. The filter reads the before-departure cancellation rules only; is_refundable on a returned fare is a wider reading of the same rules (it is true on a fare whose only decided rule allows cancellation after departure), so the flag is not this filter.

Keep only fares that allow a voluntary change. Conservative in the same way as refundable_only: unverifiable fares are dropped. The filter reads the before-departure change rules only; is_changeable on a returned fare is the wider reading refundable_only describes.

Keep only fares whose price already includes a checked bag on EVERY segment. Conservative, like refundable_only: a segment that states no allowance makes the fare unverifiable and it is dropped. The response flag of the same name is read from the first segment that states an allowance, not from every segment, so without this filter a fare flagged checked_bag_included: true can still lack a free bag on a later segment.

Keep only itineraries marketed end-to-end by one carrier.

Also search the alternate airports around each leg’s origin and destination. Widening: more results, not fewer.

Keep only itineraries whose connections leave from the same airport they arrived at (no cross-town transfer).

Keep only round trips that return to the airport the trip departed from. Round trip only: on a one-way search it is accepted and has no effect.

Keep only round trips whose return departs from the airport the outbound arrived at. Round trip only: on a one-way search it is accepted and has no effect.

TOTAL number of flights to return (1–300), not a per-page size: limit: 5 returns at most five flights. Search mode only. Omit to let the platform choose: the cheapest flight plus up to 100 alternatives, so up to 101 flights. Applied after the cross-provider merge and sort, so it only trims the returned set — the providers still bound the real count.

Adult travelers (12+). At most 9 travellers who need a seat: adults + children ≤ 9. Lap infants are not counted.

Child travelers (2–11). At most 9 travellers who need a seat: adults + children ≤ 9. Lap infants are not counted.

Infant travelers (under 2), traveling on an adult’s lap. Seated infants (own seat) are not supported.

ISO 4217 currency code, case-insensitive (eur is EUR): prices come back with the upper-case code and a display. Defaults to USD. A currency the platform cannot price in is refused with 400.

Price-check mode: re-price one known offer instead of searching a route. Route and filter fields are not allowed beside it (422); the passenger counts and currency are. Two kinds of token behave differently. A cached-itinerary offer_token from flight_calendar, find_dates, lowest_fare, find_destination or a price monitor is re-shopped LIVE on its route and dates with no cabin, stop or carrier constraint: offers[0] is the cheapest live offer with the same flights and cabin when one exists, exact_match_found says whether it did, and up to 100 alternatives follow. An offer_id from an earlier flight_search is answered from the cache of that search without re-pricing (exact_match_found: true), unless the passenger counts or currency differ, in which case it is re-shopped; once every fare of the cached offer has passed its expires_at it answers 410 OFFER_EXPIRED: search again.

Price-check mode only (request carried offer_token): true when the live offer has the same flights as the cached one. Absent in search mode.

Search mode only. no_matches means the search completed and no offer matched: relay instruction, which asks which filter to relax only when the request sent a filter that narrows the results. offers is empty. Absent when offers were found. A search that could not be completed at all answers an error instead (UPSTREAM_REJECTED, UPSTREAM_ERROR, UPSTREAM_UNAVAILABLE or UPSTREAM_TIMEOUT), never an empty list.

Present with result: no_matches: what to tell the user or do next. It attributes the empty result to the filters only when the request sent a filter that narrows the results; otherwise it reads "Search completed successfully, but no flights were found for this route and dates. Ask the user whether to try other dates or airports before searching again."