Skip to main content
POST
Cheapest fares for a fixed route + date — up to ten itineraries, cheapest first
The cheapest fares for a fixed route and date. Takes the same inputs as Flight Calendar but for one specific departure date (one-way, or with a return date for round-trip) returns up to ten itineraries sorted cheapest-first. The fixed-date counterpart of Flight Calendar. Reach for it when the date is locked and you just want the cheapest options that day. Cache-backed; no live pricing. Each result includes an offer_token to pass to flight_search for live pricing. Add the selected live fare’s trip_item_token to a trip.
Prices are in minor units. value is an integer — divide by 10 ** decimal_places to display it. { "value": 15977, "decimal_places": 2 } is $159.77, not $15,977. See Money & prices.

Authorizations

​
X-API-Key
string
header
required

Body

application/json
​
origins
string[]
required

IATA city or airport codes. See origin_type for how an untyped code is read.

Minimum array length: 1
Example:
​
trip_type
enum<string>
required
Available options:
oneway,
roundtrip
Example:

"roundtrip"

​
destinations
string[]

IATA city or airport codes. Omit for global discovery (find_destination) or to scan every destination from the origins. See destination_type for how an untyped code is read.

Example:
​
origin_type
enum<string>

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.

Available options:
city,
airport
Example:

"city"

​
destination_type
enum<string>

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.

Available options:
city,
airport
Example:

"city"

​
departure_dates
string[]
Pattern: ^\d{4}-\d{2}-\d{2}$
Example:
​
departure_date_ranges
object[]
​
return_dates
string[]
Pattern: ^\d{4}-\d{2}-\d{2}$
Example:
​
return_date_ranges
object[]
​
stay_days
integer
Required range: x > 0
Example:

7

​
stay_days_range
object
​
cabin_class
enum<string>
Available options:
economy,
premium_economy,
business,
first
Example:

"economy"

​
direct_only
boolean

Only direct flights. Cached fares record whether a fare is direct but not how many stops it makes, so this is the only stop filter here; POST /v1/flight_search takes max_stops.

Example:

false

​
accuracy
enum<string>

How strict the freshness check on cached fares is. standard (default) returns fares estimated to be at least 80% likely to still be available at the cached price; high raises that to 95%, so fewer fares come back.

Available options:
standard,
high
Example:

"standard"

​
max_total
number

Caps the cached fare's total. Cached fares are priced for one adult.

Required range: x > 0
Example:

800

​
currency
string
Example:

"USD"

​
locale
string
Example:

"en-US"

​
limit
integer
default:20

What limit counts depends on the route; 1 to 100, default 20. On flight_calendar, the maximum number of itineraries returned across the entire matching date range after sort_by is applied. This is a global result cap, not one itinerary per date pair: with the default sort_by: lowest, limit: N returns the cheapest N itineraries overall, so some matching date pairs may be absent. On find_dates, the maximum number of date pairs, each answered with its cheapest itinerary and spread across the requested departure window. On lowest_fare, not applied: that route returns at most ten itineraries, cheapest first.

Required range: 1 <= x <= 100
​
offset
integer
default:0
Required range: x >= 0
​
sort_by
enum<string>
default:lowest

The order of the results. lowest, the only order today, is cheapest first by the cached one-adult total; on find_destination it orders destinations by their cheapest itinerary. Omit it for the same order.

Available options:
lowest
​
intent
object

Response

Cheapest itineraries for the route + date, lowest-first

​
priced_for
enum<string>
required

Whose price the cached fares in this answer are: always one_adult. Every cached total is one adult's fare; this request takes no passenger counts. Price the whole party with POST /v1/flight_search.

Available options:
one_adult
Example:

"one_adult"

​
itineraries
object[]
required
​
next_page_token
string
Example:

"eyJvZmZzZXQiOjIwfQ=="