canonical: https://jentic.com/apis/amadeus.com/amadeus-flight-cheapest-date-search

# Amadeus Flight Cheapest Date Search

The Amadeus Flight Cheapest Date Search API returns the cheapest available dates to fly between two cities, ranked by total fare. The single GET endpoint at /shopping/flight-dates accepts an origin, destination, and a flexible date range and returns price points keyed by date pair, which is what powers 'when is it cheapest?' calendar widgets and flexible-date search experiences. It is intended for inspirational and flexible-date searches rather than precise booking flows.

## For AI agents

Return the cheapest dates to fly between two cities for a flexible date range. Agents call /shopping/flight-dates to power flexible-date calendar widgets.

## Scope

Does not return per-class availability, branded fare tiers, or bookable priced offers - use only for cheapest-date inspiration between two cities.

## Capabilities

- Return the cheapest fares for date pairs between two cities over a flexible window
- Filter by one-way or round-trip via the oneWay query parameter
- Constrain results by maximum price ceiling for budget-aware searches
- Surface enough date variation to build a fare calendar widget
- Power 'flexible dates' toggles in flight search UIs without a full Flight Offers Search per date
- Identify the lowest-priced travel window in a month for inspiration content

## Use cases

### Flexible-Date Calendar Widget

Travel sites compete on showing 'cheapest day to fly' calendars. The /shopping/flight-dates endpoint returns priced date pairs in one call, which is enough to colour a calendar by price band without firing a separate flight offer search per date. The endpoint is purpose-built for inspiration rather than booking, so it is much cheaper to call than full availability.

Example prompt: Call /shopping/flight-dates with origin=LON, destination=NYC, oneWay=false and return all date pairs sorted by total fare ascending.

### Budget-Capped Inspiration

A 'where can I go for under £100?' page can pin the destination and use Cheapest Date Search with a maximum price ceiling, returning only the date windows that fit the budget. This is faster and cheaper than running flight offer searches for every candidate date and trimming the response client-side.

Example prompt: Search /shopping/flight-dates with maxPrice=100 between LON and DUB and return all dates that come back within budget.

### Newsletter Deal Finding

Editorial newsletters that surface flight deals can run a nightly batch of cheapest-date searches across a watch list of routes. Each route returns a sorted list of cheapest date pairs, so the newsletter can publish 'the lowest London-to-Lisbon fare this week is £42 on Tuesday-Friday'. The single-endpoint design keeps the batch lightweight.

Example prompt: Run /shopping/flight-dates for a watch list of 30 routes nightly and surface the lowest fare per route into the newsletter draft.

### Agent Trip Planner

An AI travel agent given 'I'm flexible - when is it cheapest to fly home?' can call Cheapest Date Search with the user's origin, destination, and a window. Through Jentic the agent searches for 'find the cheapest dates to fly between two cities', loads the schema, executes, and answers in plain language with the lowest fare and its travel dates.

Example prompt: Use Jentic to call cheapest-date search for the user's flexible window and answer with the lowest fare and its travel dates.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /shopping/flight-dates | Return cheapest dates between two cities |

## Key resources

- **Flight Dates** — GET cheapest priced date pairs between two cities for a flexible window.

## Why Jentic

- **Setup:** Wiring the Flight Cheapest Date Search API by hand means running the Amadeus OAuth 2.0 client_credentials exchange, refreshing the bearer token, and parsing the priced date pairs from GET /shopping/flight-dates against the correct Amadeus host and version. Through Jentic you install once, import Flight Cheapest Date Search from the API Directory, store the Amadeus client credentials once, and your agent calls it.
- **Permission scoping:** The origin and destination cities travel as query parameters, not as a resource id in the URL path, so scoping is by operation. You limit the agent to the operations it needs, such as reading the cheapest dates between two cities, and it cannot reach availability, pricing, or booking operations unless you add them.
- **Credential handling:** Your Amadeus client_id and client_secret are stored once, encrypted, by your own Jentic One instance, which runs the client_credentials exchange and injects a fresh bearer token at execution time. The raw secret never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'find the cheapest dates to fly from London to Rome', and Jentic returns the /shopping/flight-dates operation with its input schema so the agent supplies the two cities and reads the date pairs without reading the Amadeus docs first.

## Related APIs

- **Amadeus Flight Availabilities Search** — Returns per-class availability rather than cheapest dates.
- **Amadeus Flight Inspiration Search** — Inspiration by destination from a given origin within a budget, rather than cheapest dates between fixed cities.
- **Amadeus Flight Offers Price** — Confirms a bookable fare for the chosen date pair from cheapest-date search.

## FAQ

### What authentication does the Flight Cheapest Date Search API use?

The API uses the Amadeus OAuth 2.0 client-credentials flow. Exchange API key and secret at the Amadeus token endpoint and send the bearer token on the /shopping/flight-dates request. Jentic stores the credentials in the encrypted vault and refreshes the token automatically.

### Are the returned fares bookable?

The endpoint is intended for inspirational and flexible-date searches; the prices indicate the lowest fares Amadeus has seen for those date pairs. To book, follow up with a Flight Offers Search and Flight Offers Price call against the chosen date pair to confirm the fare is still bookable.

### What are the rate limits for the Flight Cheapest Date Search API?

Rate limits are not declared in the OpenAPI spec and depend on the Amadeus contract tier. The call returns many date pairs in a single response, which makes it cheaper than calling Flight Offers Search per date - still cache responses keyed on origin, destination, and window to stay under the per-second cap.

### How do I find the cheapest date through Jentic?

Run pip install jentic, then use the search query 'find the cheapest dates to fly between two cities'. Jentic returns the /shopping/flight-dates operation, you load the schema, supply origin, destination, and oneWay, and execute. The response gives the cheapest date pairs ready to render in a calendar widget.

### Can I cap results to a maximum fare?

Yes. Pass maxPrice on the request to limit results to date pairs that fall under the supplied amount. This is the right way to power 'where can I go for under £100?' style inspiration pages.

### Is the Flight Cheapest Date Search API free?

Amadeus self-service APIs include a free test environment with quota limits and a paid production tier. Production pricing depends on transaction volume and is set by contract - confirm current rates in the Amadeus self-service developer portal.

### Can I limit what my agent is allowed to do with the Flight Cheapest Date Search API?

Yes. This API exposes a single operation, GET /shopping/flight-dates, which reads the cheapest date pairs between two cities, so with your self-hosted Jentic One instance you decide which operations your agent may call and scope it to just cheapest-date reads. Because the origin and destination travel as query parameters rather than as a resource id in the URL path, scoping is by operation: the agent cannot reach availability, pricing, or booking operations unless you explicitly add them under your own rules. Your Amadeus client credentials are held by your Jentic One instance and injected at execution time, so the agent runs the calls you permit without ever seeing the raw secret.