For AI agents: a documentation index is available at https://docs.parallel.ai/llms.txt. The full text of all docs is at https://docs.parallel.ai/llms-full.txt. You may also fetch any page as Markdown by appending
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.
.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 before you build the harness, especially its 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.Request Fields
Send requests toPOST 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.
Example
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’scurrency: 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 itssegments(one per flight) and thelayoversbetween them. Times are local to each airport.overnightmarks a flight or layover that crosses midnight.inbound: the return trip, in the same shape. Set for round trips only.
Round Trips
Addreturn_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.
originsanddestinationstake 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.