Search for flights (legs-based itinerary)

Overview

Search for available flights with real-time pricing from multiple providers. The itinerary must be sent as a non-empty legs array. Each leg follows the provider SearchLeg shape: required origin, destination, and date (YYYY-MM-DD); optional direction (OUTBOUND or INBOUND); optional per-leg filters that override global filters for that leg only.

Not supported: top-level origin, destination, departureDate, or returnDate — use legs only.

When to Use

Listings — live prices for search results UI
One-way, round-trip, or multi-city — one leg per segment, in order
Filtering — cabin class, stops, price, refundability, times (globally or per leg)
Streaming — incremental provider results over SSE

What You Get

Offers from multiple providers
Itineraries with segments, layovers, and durations
Price breakdown (fares, taxes, fees) and baggage hints

Key Features

Multi-provider aggregation in one request
SSE: send header Accept: text/event-stream on POST /flights/rates, or POST /flights/rates/stream with the same JSON body
Global filters, sort

Quick Start

Required: legs (at least one object with origin, destination, date), adults (≥ 1), currency

Round-trip: two legs (e.g. outbound then return with direction OUTBOUND / INBOUND). One-way: one leg.

Request body

adultsinteger required

Number of adults (12+)

childreninteger

Number of children (2-11)

infantsinteger

Number of infants (<2)

childrenAgesinteger[]

Age of each child (2–11 inclusive, per IATA). Length must equal children count. Optional — omit if ages are not relevant.

infantAgesinteger[]

Age of each infant (under 2, per IATA). Length must equal infants count. Optional — omit if ages are not relevant.

cabinClass'ECONOMY' | 'PREMIUM_ECONOMY' | 'BUSINESS' | 'FIRST'

Cabin class (provider SearchFilters codes only). Same enum as filters.cabinClass.

currencystring required

ISO 4217 currency code

countrystring

Optional ISO 3166-1 alpha-2 country code for point of sale

Example request

{
  "legs": [
    {
      "origin": "JFK",
      "destination": "CDG",
      "date": "2026-07-01",
      "direction": "OUTBOUND"
    },
    {
      "origin": "CDG",
      "destination": "JFK",
      "date": "2026-08-02",
      "direction": "INBOUND"
    }
  ],
  "adults": 1,
  "childrenAges": [
    5,
    11
  ],
  "infantAges": [
    1
  ],
  "cabinClass": "ECONOMY",
  "currency": "USD",
  "country": "US",
  "filters": {
    "maxStops": 1,
    "maxPrice": 1500,
    "includesCheckedBag": false,
    "refundableOnly": false
  },
  "sort": {
    "sortBy": "price",
    "sortOrder": "asc"
  }
}

Response

Successful response

v1