> ## 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 Quickstart

> Find one-way and round-trip flight itineraries with 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.

The **Flights API** takes origin and destination airports, a departure date and an
optional return date, and returns flight itineraries. Each result includes the flights, local
departure and arrival times, stops and layovers, the lowest listed fare when one is known (in
US dollars unless you set `currency`), and a link to book.

Use the Flights API when an agent or application needs bookable flight options: planning a
trip, comparing routes and departure times, or checking fares for a date.

## 1. Set Up Prerequisites

Generate your API key on [Platform](https://platform.parallel.ai), then export it:

```bash theme={"system"}
export PARALLEL_API_KEY="PARALLEL_API_KEY"
```

The Python example below uses `requests` (`pip install requests`).

## 2. Make Your First Flights API Request

### Sample Request

The samples use a fixed `departure_date`. The API rejects a date that has passed, so replace
it with a future date before you run them.

```bash cURL theme={"system"}
curl https://api.parallel.ai/v1/flights/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PARALLEL_API_KEY" \
  -d '{
    "origins": ["SFO"],
    "destinations": ["JFK"],
    "departure_date": "2026-12-01",
    "advanced_settings": {"max_results": 5}
  }'
```

```python Python theme={"system"}
import os

import requests

response = requests.post(
    "https://api.parallel.ai/v1/flights/search",
    headers={"x-api-key": os.environ["PARALLEL_API_KEY"]},
    json={
        "origins": ["SFO"],
        "destinations": ["JFK"],
        "departure_date": "2026-12-01",
        "advanced_settings": {"max_results": 5},
    },
    timeout=60,
)
response.raise_for_status()

for result in response.json()["results"]:
    leg = result["outbound"]
    flights = " + ".join(segment["flight_number"] for segment in leg["segments"])
    price = f"${result['price']}" if "price" in result else "no price"
    print(f"{flights}: {leg['departure_time']} to {leg['arrival_time']}, {price}")
    print(f"  book at {result['url']}")
```

```typescript TypeScript theme={"system"}
async function main() {
    const response = await fetch("https://api.parallel.ai/v1/flights/search", {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "x-api-key": process.env.PARALLEL_API_KEY!,
        },
        body: JSON.stringify({
            origins: ["SFO"],
            destinations: ["JFK"],
            departure_date: "2026-12-01",
            advanced_settings: { max_results: 5 },
        }),
    });
    if (!response.ok) {
        throw new Error(`Flights API request failed: ${response.status} ${await response.text()}`);
    }

    const { results } = await response.json();
    for (const result of results) {
        const leg = result.outbound;
        const flights = leg.segments
            .map((segment: { flight_number: string }) => segment.flight_number)
            .join(" + ");
        const price = result.price !== undefined ? `$${result.price}` : "no price";
        console.log(`${flights}: ${leg.departure_time} to ${leg.arrival_time}, ${price}`);
        console.log(`  book at ${result.url}`);
    }
}

main().catch(console.error);
```

### Sample Response

The API returns a JSON response with the following structure. The `results` array below is
shortened to a one-stop and a nonstop itinerary. Fields that are not known for an itinerary,
such as its price, are left out.

```json theme={"system"}
{
  "search_id": "search_68179b69a6b4d39c7a5ea5bc1ffc5003",
  "session_id": "session_68179b69a6b4d39c7a5ea5bc1ffc5003",
  "results": [
    {
      "url": "https://www.aa.com/booking/search?locale=en_US&pax=1&adult=1&child=0&type=OneWay&searchType=Revenue&cabin=&carriers=ALL&slices=%5B%7B%22orig%22%3A%22SFO%22%2C%22origNearby%22%3Afalse%2C%22dest%22%3A%22JFK%22%2C%22destNearby%22%3Afalse%2C%22date%22%3A%222026-12-01%22%7D%5D&maxAwardSegmentAllowed=2",
      "price": 219.0,
      "outbound": {
        "departure_airport": "SFO",
        "departure_time": "2026-12-01 10:39",
        "arrival_airport": "JFK",
        "arrival_time": "2026-12-01 21:59",
        "duration_minutes": 500,
        "stops": 1,
        "segments": [
          {
            "airline": "American",
            "flight_number": "AA 4983",
            "departure_airport": "SFO",
            "departure_time": "2026-12-01 10:39",
            "arrival_airport": "LAX",
            "arrival_time": "2026-12-01 12:13",
            "duration_minutes": 94,
            "aircraft": "Embraer 175",
            "cabin": "Economy",
            "legroom": "30 in",
            "overnight": false
          },
          {
            "airline": "American",
            "flight_number": "AA 4",
            "departure_airport": "LAX",
            "departure_time": "2026-12-01 13:44",
            "arrival_airport": "JFK",
            "arrival_time": "2026-12-01 21:59",
            "duration_minutes": 315,
            "aircraft": "Boeing 777",
            "cabin": "Economy",
            "legroom": "31 in",
            "overnight": false
          }
        ],
        "layovers": [
          {
            "airport": "LAX",
            "duration_minutes": 91,
            "overnight": false
          }
        ]
      }
    },
    {
      "url": "https://www.jetblue.com/booking/flights?from=SFO&to=JFK&depart=2026-12-01&isMultiCity=false&noOfRoute=1&adults=1&children=0&infants=0&roundTripFaresFlag=false&sharedMarket=false&usePoints=false",
      "price": 268.0,
      "outbound": {
        "departure_airport": "SFO",
        "departure_time": "2026-12-01 23:32",
        "arrival_airport": "JFK",
        "arrival_time": "2026-12-02 08:03",
        "duration_minutes": 331,
        "stops": 0,
        "segments": [
          {
            "airline": "JetBlue",
            "flight_number": "B6 616",
            "departure_airport": "SFO",
            "departure_time": "2026-12-01 23:32",
            "arrival_airport": "JFK",
            "arrival_time": "2026-12-02 08:03",
            "duration_minutes": 331,
            "aircraft": "Airbus A320",
            "cabin": "Economy",
            "legroom": "32 in",
            "overnight": true
          }
        ],
        "layovers": []
      }
    }
  ],
  "usage": [
    {
      "name": "sku_search",
      "count": 1
    }
  ]
}
```

See [Response](https://docs.parallel.ai/flight-search/best-practices.md#response) for how to read each field.

## 3. Search a Round Trip

Add `"return_date": "2026-12-08"` to the request. Each result then also has an `inbound` leg,
on the same airline as `outbound`, and `price` is the round-trip fare. See
[Round Trips](https://docs.parallel.ai/flight-search/best-practices.md#round-trips) for how the return flight is chosen.

## Next Steps

* **[Best Practices](https://docs.parallel.ai/flight-search/best-practices.md)**: every request field, with examples
* **[Pricing](https://docs.parallel.ai/getting-started/pricing.md#flights-api)**: per-request cost
* **[Rate Limits](https://docs.parallel.ai/getting-started/rate-limits.md)**: default quotas per product
