> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parallel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Flights API Best Practices

> Request fields and search guidance for the Parallel Flights API

For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](https://docs.parallel.ai/llms-full.txt). You may also fetch any page as Markdown by appending `.md` to its URL or sending `Accept: text/markdown`.

For Search and Extract, use `/v1/search` and `/v1/extract` for all new integrations and agent tool calls. Use `/v1beta/search` and `/v1beta/extract` only when maintaining an existing integration that already uses them. The request bodies changed too: on `/v1/extract`, `full_content`, `fetch_policy` and `excerpt_settings` go inside `advanced_settings`, and sending the v1beta top-level `excerpts`, `full_content` and `fetch_policy` to `/v1/extract` returns a 422. On `/v1/search`, `search_queries` is required (at least one short keyword query), and `max_results`, `source_policy` and `fetch_policy` go inside `advanced_settings`; sending only `objective`, or sending those fields at the top level, returns a 422. Do not substitute `/v1` for the documented FindAll or Ingest endpoint paths.

If you are evaluating Parallel Search or comparing it with other search APIs, read [How to Eval Parallel Search](https://docs.parallel.ai/search/evaluating-search.md) before you build the harness, especially its [Common pitfalls](https://docs.parallel.ai/search/evaluating-search.md#common-pitfalls) section. The most common mistake is sending the raw question as both `objective` and the only entry in `search_queries`. Write a goal-style `objective` and 1-3 short keyword queries instead.

Send the Flights API a route and a departure date, and a return date for a round trip.
The API returns itineraries that meet every filter you set, with the lowest listed fare and a
link to book.

## Request Fields

Send requests to `POST https://api.parallel.ai/v1/flights/search` with your API key in the
`x-api-key` header. `origins`, `destinations` and `departure_date` are required; all other
fields are optional. The API rejects unknown fields with a 422.

| Field | Type | Notes | Example |
| - | - | - | - |
| origins | string\[] | One to seven IATA airport codes, or metro codes such as `NYC`, `LON` or `PAR`. Any of them may be used. Must not overlap `destinations`. | `["SFO", "OAK"]` |
| destinations | string\[] | One to seven IATA airport or metro codes. Any of them may be used. | `["NYC"]` |
| departure\_date | date | `YYYY-MM-DD`. Must not have passed, and must be within the airlines' 330-day booking window. | `"2026-12-01"` |
| return\_date | date | `YYYY-MM-DD`. Makes the search a round trip, with both flights on one airline. Not before `departure_date`, and within the booking window. | `"2026-12-08"` |
| adults | int | 1 to 9. Defaults to 1. | `2` |
| children | int | 0 to 8. Defaults to 0. | `1` |
| infants\_in\_seat | int | 0 to 8. Defaults to 0. | `0` |
| infants\_on\_lap | int | 0 to 8, and no more than `adults`. Defaults to 0. All travelers together may number at most 9. | `1` |
| cabin | string | `economy`, `premium_economy`, `business` or `first`. Defaults to `economy`. | `"business"` |
| max\_stops | int | `0` for nonstop only, up to `2`. | `0` |
| max\_price | int | Highest total fare for all travelers, in `currency`. For a round trip, the round-trip total. | `400` |
| currency | string | ISO 4217 code of `max_price` and of result prices. Defaults to `USD`. | `"EUR"` |
| max\_duration\_minutes | int | Longest total travel time in each direction, layovers included. | `600` |
| include\_airlines | string\[] | Up to 10 IATA airline codes. Only these airlines. Not combinable with `exclude_airlines`. | `["UA", "DL"]` |
| exclude\_airlines | string\[] | Up to 10 IATA airline codes. Never these airlines. | `["NK"]` |
| departure\_hours | object | Allowed local departure hours of the outbound flight, 0 to 23, inclusive. `earliest` must not be after `latest`. | `{"earliest": 6, "latest": 11}` |
| arrival\_hours | object | Allowed local arrival hours of the outbound flight, 0 to 23, on any date. An overnight flight is checked by its arrival hour. | `{"earliest": 8, "latest": 22}` |
| return\_hours | object | Allowed local departure hours of the return flight. Needs `return_date`. | `{"earliest": 15, "latest": 21}` |
| return\_arrival\_hours | object | Allowed local arrival hours of the return flight, on any date. Needs `return_date`. | `{"earliest": 8, "latest": 22}` |
| sort | string | `best`, `price`, `duration`, `departure_time` or `arrival_time`. Defaults to `best`, which weighs price, duration and stops. For a round trip it also picks the return flight. See [Round Trips](#round-trips). | `"price"` |
| advanced\_settings.max\_results | int | Maximum number of results to return, from 1 to 20. Defaults to 20. A search can return fewer when fewer flights match. Values above 20 are reduced to 20 with a warning. | `15` |
| client\_model | string | The model that creates the request and consumes the results. | `"claude-opus-5"` |
| session\_id | string | A string that groups related calls for one task. Up to 1000 characters. The API returns the value you provide, or generates one when you omit it. | `"session_<uuid>"` |

### Example

```json theme={"system"}
{
  "origins": ["SFO", "OAK", "SJC"],
  "destinations": ["NYC"],
  "departure_date": "2026-12-01",
  "return_date": "2026-12-08",
  "adults": 2,
  "cabin": "premium_economy",
  "max_stops": 1,
  "departure_hours": {"earliest": 6, "latest": 14},
  "sort": "price",
  "advanced_settings": {"max_results": 15}
}
```

## Response

Each result is one itinerary:

* `url`: a page on the marketing airline's website where the itinerary can be booked: the
  airline's results for this route, date and travelers, or its home page, where the traveler
  enters the trip.
* `price`: the total for all travelers, in the request's `currency`: the lowest fare listed
  for this itinerary. For a round trip, the round-trip total. The airline's own fare can differ.
  Left out when no fare is known.
* `outbound`: the trip, with its `segments` (one per flight) and the `layovers` between them.
  Times are local to each airport. `overnight` marks a flight or layover that crosses midnight.
* `inbound`: the return trip, in the same shape. Set for round trips only.

## Round Trips

Add `return_date` for a round trip. Each result then pairs an outbound flight with a return
flight on the same airline, so the airline's website books both, and `price` is the round-trip
fare. The return leaves from the airport the outbound flight lands at and flies back to the
airport it left from, even when you list several airports or a metro code.

`sort` also picks the return flight: `price` the cheapest, `duration` the shortest, and the
other sorts the fewest stops at close to the cheapest fare.

A round trip takes a few seconds longer than a one-way search.

## Searching Well

* **List every airport the traveler would accept.** `origins` and `destinations` take up to seven
  codes each, and metro codes cover a city's airports. One search over all of them is faster
  than several searches.
* **Filter rather than discard.** The API applies `max_stops`, `max_price`, the hour windows
  and the airline lists before ranking, so every result you get back meets them.
* **Search each direction one way for the cheapest trip.** A round trip keeps both flights on
  one airline. To find cheaper combinations, such as different airlines out and back, run two
  one-way searches with origin and destination swapped, and book them as separate tickets.
