---
title: "Search for flights (legs-based itinerary)"
method: POST
path: "/flights/rates"
tags: ["Flight Search"]
---

# Search for flights (legs-based itinerary)

`POST /flights/rates`

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

- object
  - `legs` object[], required — Ordered itinerary legs (provider SearchLeg). One-way: one entry. Round-trip: outbound then inbound. Multi-city / open-jaw: additional legs in travel order.
    - `origin` string, required — Origin airport or city IATA code for this leg
    - `destination` string, required — Destination airport or city IATA code for this leg
    - `date` string, date, required — Departure date for this leg (YYYY-MM-DD)
    - `direction` 'OUTBOUND' | 'INBOUND' — Leg direction (optional; defaults to OUTBOUND on the provider)
    - `filters` object — Optional per-leg filters overriding global `filters` for this leg
      - `departureTimeAfter` string — Departure after this local time (HH:MM, 24h)
      - `departureTimeBefore` string — Departure before this local time (HH:MM, 24h)
      - `arrivalTimeAfter` string — Arrival after this local time (HH:MM, 24h)
      - `arrivalTimeBefore` string — Arrival before this local time (HH:MM, 24h)
      - `excludeConnectionAirports` string[]
      - `excludeOvernight` boolean
      - `flightNumbers` string[]
      - `flightNumbersMatch` 'any' | 'all'
      - `maxDuration` integer — Max leg duration in minutes
      - `maxStops` integer
  - `adults` integer, required — Number of adults (12+)
  - `children` integer — Number of children (2-11)
  - `infants` integer — Number of infants (<2)
  - `childrenAges` integer[] — Age of each child (2–11 inclusive, per IATA). Length must equal children count. Optional — omit if ages are not relevant.
  - `infantAges` integer[] — 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.
  - `currency` string, required — ISO 4217 currency code
  - `country` string — Optional ISO 3166-1 alpha-2 country code for point of sale
  - `filters` object — Optional filters to refine search results
    - `arrivalTimeBefore` string — Filter journeys arriving before this time (HH:MM, 24h)
    - `cabinClass` 'ECONOMY' | 'PREMIUM_ECONOMY' | 'BUSINESS' | 'FIRST' | 'Economy' | 'Business' | 'First' — Cabin class filter (maps to provider SearchFilters.cabinClass). Overrides top-level cabinClass for this field when both are set.
    - `cabinClassMatch` 'exactly' | 'at_least' — 'exactly' for exact match, 'at_least' for selected cabin or better
    - `changeableOnly` boolean — When true, only show offers with changeable (modifiable) fares
    - `departureTimeBefore` string — Filter journeys departing before this time (HH:MM, 24h)
    - `excludeConnectionAirports` string[] — Exclude layovers at these airports (e.g. IST, DOH)
    - `excludeOvernight` boolean — Exclude red-eye flights and overnight layovers
    - `flightNumbers` string[] — Filter by flight numbers (e.g. SK500, AF123)
    - `flightNumbersMatch` 'any' | 'all' — 'any' = at least one match, 'all' = all specified flights
    - `includesCarryOnBag` boolean — Only show offers with carry-on included
    - `includesCheckedBag` boolean — Only show offers with checked bag included
    - `legDurations` object[] — Per-leg max duration constraints. Each entry limits one direction (OUTBOUND or INBOUND) independently.
      - `direction` 'OUTBOUND' | 'INBOUND', required — Which leg to constrain
      - `maxMinutes` integer, required — Maximum leg duration in minutes (inclusive)
    - `maxDuration` integer, nullable — Maximum total journey duration in minutes (inclusive). Journeys exceeding this duration are excluded.
    - `maxPrice` number — Maximum total price (offer total, in search currency)
    - `minPrice` number — Minimum total price (offer total, in search currency)
    - `maxStops` integer, nullable — Maximum number of stops: -1 or omit = any, 0 = nonstop, 1 = 1 or fewer, 2 = 2 or fewer
    - `refundableOnly` boolean — When true, only show offers with refundable fares
    - `showCheapestOfferOnly` boolean — Return only cheapest offer per journey
  - `sort` object — Sort options for results
    - `sortBy` 'price' | 'duration' | 'departure' | 'arrival' | 'stops' — Sort by price, duration, departure, arrival, or stops
    - `sortOrder` 'asc' | 'desc' — asc or desc

## Response `200`

Successful response

- object
  - `data` object[] — List of search result sets, one per provider batch
    - `journeys` FlightJourney[] — Journeys returned by this provider batch, sorted by price ascending
      - `journeyKey` string — Unique identifier for this journey (hash of route, flights, and times)
      - `isCheapest` boolean — True if this is the cheapest journey across all results
      - `cheapestOffer` FlightOffer — A bookable offer for a journey, including pricing, baggage policy, fare details, and booking terms
        - `offerId` string — Unique offer identifier
        - `expiration` string — Offer expiration time (ISO 8601)
        - `pricing` FlightOfferPricing — Full offer pricing with per-passenger breakdown
          - `display` FlightPrice — Full price breakdown including base fare, taxes, fees, and per-passenger amounts
            - `base` number — Base fare amount (before taxes and fees)
            - `currency` string — ISO 4217 currency code
            - `fees` number — Service fees and surcharges
            - `taxes` number — Total taxes applied to the fare
            - `total` number — Total price (base + taxes + fees)
            - `perPassenger` object — Price breakdown per passenger type
              - …
          - `converted` boolean — True if FX currency conversion was applied
        - `fare` object — Fare class information
          - `family` string — Fare family name (e.g. Economy, Business, First)
          - `mixedCabin` boolean — True if outbound and inbound legs are in different cabin classes
          - `seatsRemaining` integer — Number of seats remaining at this fare
        - `terms` object — Booking terms and conditions for this offer
          - `changeable` boolean — True if the fare allows changes (rebooking)
          - `refundable` boolean — True if the fare is refundable
          - `summary` object[] — Human-readable policy messages with severity levels
            - `level` string — Severity: info, warning, or danger
            - `message` string — Policy message text (e.g. Non-refundable, Changes allowed with fee)
          - `changeFee` FlightFee, nullable — Change or refund fee published by the provider. Null when the provider does not publish a fee.
            - `pricing` object, nullable — Fee pricing; null when only a percentage is available
              - …
            - `percent` number, nullable — Fee as a percentage of the base fare (e.g. 100 = full penalty). May appear without pricing.
            - `applicability` 'anytime' | 'noShow' | 'beforeDeparture' | 'afterDeparture' — When the fee applies
            - `label` string — Human-readable fee description (e.g. 'Change fee (before departure)')
          - `refundFee` FlightFee, nullable — Change or refund fee published by the provider. Null when the provider does not publish a fee.
            - `pricing` object, nullable — Fee pricing; null when only a percentage is available
              - …
            - `percent` number, nullable — Fee as a percentage of the base fare (e.g. 100 = full penalty). May appear without pricing.
            - `applicability` 'anytime' | 'noShow' | 'beforeDeparture' | 'afterDeparture' — When the fee applies
            - `label` string — Human-readable fee description (e.g. 'Change fee (before departure)')
          - `hasChangeFee` boolean — True when the provider signalled that a change fee applies to the fare, even when the actual amount is not published in `changeFee`. Lets clients render a "change fee applies — amount on request" remark for fares where the rule is known but the monetary amount is not exposed (common for LCC content distributed via GDS, e.g. U2 / easyJet via Sabre). When `false` or absent, no change fee is known to apply.
          - `hasRefundFee` boolean — True when the provider signalled that a refund/cancellation fee applies to the fare, even when the actual amount is not published in `refundFee`. Lets clients render a "cancellation fee applies — amount on request" remark for fares where the rule is known but the monetary amount is not exposed. When `false` or absent, no refund fee is known to apply.
        - `baggage` object — Baggage policy for this offer
          - `hasCarryOnBag` boolean — Whether carry-on bag is included
          - `hasCheckedBag` boolean — Whether checked bag is included
          - `included` object[] — List of included baggage allowances
            - `bagType` 'cabin' | 'checked' — Type of bag
            - `description` string — Human-readable baggage description
            - `passengerType` 'ADT' | 'CHD' | 'INF' — Passenger type this allowance applies to
            - `pieces` integer — Number of pieces allowed
            - `pricing` FlightItemPricing — Pricing for an ancillary item (e.g. baggage)
              - …
            - `unit` string — Weight unit (e.g. kg)
            - `weightKg` number — Weight limit in kg
        - `segmentFares` object[] — Per-segment fare details
          - `bookingCode` string — Booking/RBD class code (e.g. W, Y, J)
          - `cabin` string — Cabin class (e.g. Economy, Business, First)
          - `fareBasisCode` string — Fare basis code
          - `fareFamily` string — Fare family name
          - `seatsRemaining` integer — Number of seats remaining at this fare
          - `segmentKey` string — Links to the segment this fare applies to
        - `segmentAmenities` FlightSegmentAmenities[] — Per-segment amenity data (each entry linked by segmentKey)
          - `aircraftType` string — Aircraft model for this segment
          - `amenities` FlightAmenity[] — List of amenities available on this segment
            - `available` boolean — Whether this amenity is offered on this segment
            - `category` 'wifi' | 'power' | 'entertainment' | 'food' | 'seat_comfort' — Amenity category
            - `chargeable` boolean, nullable — True if paid, False if free, null if unknown
            - `details` string, nullable — Additional details (e.g. 'Streaming only', '34 inch pitch')
            - `name` string — Human-readable amenity name
          - `segmentKey` string — Links to the segment this amenities data belongs to (matches segment.segmentKey)
      - `offers` FlightOffer[] — All available provider offers for this journey, sorted by price ascending
        - `offerId` string — Unique offer identifier
        - `expiration` string — Offer expiration time (ISO 8601)
        - `pricing` FlightOfferPricing — Full offer pricing with per-passenger breakdown
          - `display` FlightPrice — Full price breakdown including base fare, taxes, fees, and per-passenger amounts
            - `base` number — Base fare amount (before taxes and fees)
            - `currency` string — ISO 4217 currency code
            - `fees` number — Service fees and surcharges
            - `taxes` number — Total taxes applied to the fare
            - `total` number — Total price (base + taxes + fees)
            - `perPassenger` object — Price breakdown per passenger type
              - …
          - `converted` boolean — True if FX currency conversion was applied
        - `fare` object — Fare class information
          - `family` string — Fare family name (e.g. Economy, Business, First)
          - `mixedCabin` boolean — True if outbound and inbound legs are in different cabin classes
          - `seatsRemaining` integer — Number of seats remaining at this fare
        - `terms` object — Booking terms and conditions for this offer
          - `changeable` boolean — True if the fare allows changes (rebooking)
          - `refundable` boolean — True if the fare is refundable
          - `summary` object[] — Human-readable policy messages with severity levels
            - `level` string — Severity: info, warning, or danger
            - `message` string — Policy message text (e.g. Non-refundable, Changes allowed with fee)
          - `changeFee` FlightFee, nullable — Change or refund fee published by the provider. Null when the provider does not publish a fee.
            - `pricing` object, nullable — Fee pricing; null when only a percentage is available
              - …
            - `percent` number, nullable — Fee as a percentage of the base fare (e.g. 100 = full penalty). May appear without pricing.
            - `applicability` 'anytime' | 'noShow' | 'beforeDeparture' | 'afterDeparture' — When the fee applies
            - `label` string — Human-readable fee description (e.g. 'Change fee (before departure)')
          - `refundFee` FlightFee, nullable — Change or refund fee published by the provider. Null when the provider does not publish a fee.
            - `pricing` object, nullable — Fee pricing; null when only a percentage is available
              - …
            - `percent` number, nullable — Fee as a percentage of the base fare (e.g. 100 = full penalty). May appear without pricing.
            - `applicability` 'anytime' | 'noShow' | 'beforeDeparture' | 'afterDeparture' — When the fee applies
            - `label` string — Human-readable fee description (e.g. 'Change fee (before departure)')
          - `hasChangeFee` boolean — True when the provider signalled that a change fee applies to the fare, even when the actual amount is not published in `changeFee`. Lets clients render a "change fee applies — amount on request" remark for fares where the rule is known but the monetary amount is not exposed (common for LCC content distributed via GDS, e.g. U2 / easyJet via Sabre). When `false` or absent, no change fee is known to apply.
          - `hasRefundFee` boolean — True when the provider signalled that a refund/cancellation fee applies to the fare, even when the actual amount is not published in `refundFee`. Lets clients render a "cancellation fee applies — amount on request" remark for fares where the rule is known but the monetary amount is not exposed. When `false` or absent, no refund fee is known to apply.
        - `baggage` object — Baggage policy for this offer
          - `hasCarryOnBag` boolean — Whether carry-on bag is included
          - `hasCheckedBag` boolean — Whether checked bag is included
          - `included` object[] — List of included baggage allowances
            - `bagType` 'cabin' | 'checked' — Type of bag
            - `description` string — Human-readable baggage description
            - `passengerType` 'ADT' | 'CHD' | 'INF' — Passenger type this allowance applies to
            - `pieces` integer — Number of pieces allowed
            - `pricing` FlightItemPricing — Pricing for an ancillary item (e.g. baggage)
              - …
            - `unit` string — Weight unit (e.g. kg)
            - `weightKg` number — Weight limit in kg
        - `segmentFares` object[] — Per-segment fare details
          - `bookingCode` string — Booking/RBD class code (e.g. W, Y, J)
          - `cabin` string — Cabin class (e.g. Economy, Business, First)
          - `fareBasisCode` string — Fare basis code
          - `fareFamily` string — Fare family name
          - `seatsRemaining` integer — Number of seats remaining at this fare
          - `segmentKey` string — Links to the segment this fare applies to
        - `segmentAmenities` FlightSegmentAmenities[] — Per-segment amenity data (each entry linked by segmentKey)
          - `aircraftType` string — Aircraft model for this segment
          - `amenities` FlightAmenity[] — List of amenities available on this segment
            - `available` boolean — Whether this amenity is offered on this segment
            - `category` 'wifi' | 'power' | 'entertainment' | 'food' | 'seat_comfort' — Amenity category
            - `chargeable` boolean, nullable — True if paid, False if free, null if unknown
            - `details` string, nullable — Additional details (e.g. 'Streaming only', '34 inch pitch')
            - `name` string — Human-readable amenity name
          - `segmentKey` string — Links to the segment this amenities data belongs to (matches segment.segmentKey)
      - `segments` FlightSegment[] — Ordered list of flight segments that make up this journey
        - `arrivalTime` string — Arrival time (ISO 8601)
        - `carrier` object — Marketing and operating carrier details for this segment
          - `marketingCode` string — Marketing carrier IATA code
          - `marketingLogo` string — Marketing carrier logo path/URL
          - `marketingName` string — Marketing carrier name
          - `operatingCode` string — Operating carrier IATA code
          - `operatingLogo` string — Operating carrier logo path/URL
          - `operatingName` string — Operating carrier name
        - `departureTime` string — Departure time (ISO 8601)
        - `destinationCode` string — Destination IATA code
        - `direction` string — OUTBOUND or INBOUND
        - `duration` object — Flight duration in ISO 8601 and minutes
          - `iso8601` string — Duration in ISO 8601 format (e.g. PT7H45M)
          - `minutes` integer — Duration in minutes
        - `flight` object — Marketing and operating flight numbers
          - `marketingNumber` string — Flight number as marketed to passengers
          - `operatingNumber` string — Flight number as operated by the carrier
        - `originCode` string — Origin IATA code
        - `originName` string — Full name of the origin airport
        - `destinationName` string — Full name of the destination airport
        - `segmentKey` string — Unique identifier for this segment, used to link with offers, fares, and amenities
      - `parameters` object — Passenger composition used in the search that produced this journey
        - `adults` integer — Number of adult passengers
        - `children` integer — Number of child passengers
        - `infants` integer — Number of infant passengers
      - `timestamp` string — UTC timestamp when this journey was retrieved from the provider
      - `legDurations` FlightLegDuration[] — Per-direction elapsed times including layovers (outbound and/or inbound)
        - `dayChange` integer — Number of calendar days added crossing midnight (0 = same day arrival, 1 = next day, etc.)
        - `direction` 'OUTBOUND' | 'INBOUND' — Which leg this duration applies to
        - `duration` FlightDuration — Duration expressed in both ISO 8601 format and minutes
          - `iso8601` string — Duration in ISO 8601 format (e.g. PT2H30M)
          - `minutes` integer — Duration in minutes
        - `overnightFlight` boolean — True if the flight departs and arrives on different calendar days
      - `totalDuration` FlightDuration — Duration expressed in both ISO 8601 format and minutes
        - `iso8601` string — Duration in ISO 8601 format (e.g. PT2H30M)
        - `minutes` integer — Duration in minutes
      - `connections` FlightConnection[] — Layover details between consecutive segments
        - `arrivalAirportCode` string — IATA code of the airport where the passenger arrives for this connection
        - `arrivalAirportName` string — Full name of the arrival airport for this connection
        - `arrivalTime` string — UTC ISO 8601 arrival time at the connection airport
        - `changeAirport` boolean — True if the passenger must change airports during this connection
        - `departureAirportCode` string — IATA code of the airport from which the passenger departs after layover
        - `departureAirportName` string — Full name of the departure airport after layover
        - `departureTime` string — UTC ISO 8601 departure time from the connection airport
        - `direction` 'OUTBOUND' | 'INBOUND' — Which leg of the journey this connection belongs to (OUTBOUND or INBOUND)
        - `duration` FlightDuration — Duration expressed in both ISO 8601 format and minutes
          - `iso8601` string — Duration in ISO 8601 format (e.g. PT2H30M)
          - `minutes` integer — Duration in minutes
        - `overnight` boolean — True if the layover crosses midnight (arrival and departure on different calendar days)
    - `sortMetadata` object, nullable — Precomputed winner references for each sort criterion. Use the `offerId` to quickly look up the winning offer in `journeys[].offers[]`. Sent with every response (including SSE partial results) so the frontend can keep stable sort-tab labels without recalculating.
      - `best` FlightSortOptionMeta — Winner reference for a single sort criterion. The `offerId` matches a `journeys[].offers[].offerId` in the same response, allowing fast lookup of the winning offer's full details.
        - `journeyKey` string, nullable — The journeyKey of the winning journey for this sort criterion
        - `offerId` string, nullable — The offerId of the winning offer (matches `journeys[].offers[].offerId`). Present for offer-centric criteria (best, price); may be null for journey-centric criteria (duration, stops).
        - `price` number — Display total price of the winning offer (with margin applied)
        - `currency` string — Currency code of the price (e.g. USD, EUR)
      - `duration` FlightSortOptionMeta — Winner reference for a single sort criterion. The `offerId` matches a `journeys[].offers[].offerId` in the same response, allowing fast lookup of the winning offer's full details.
        - `journeyKey` string, nullable — The journeyKey of the winning journey for this sort criterion
        - `offerId` string, nullable — The offerId of the winning offer (matches `journeys[].offers[].offerId`). Present for offer-centric criteria (best, price); may be null for journey-centric criteria (duration, stops).
        - `price` number — Display total price of the winning offer (with margin applied)
        - `currency` string — Currency code of the price (e.g. USD, EUR)
      - `price` FlightSortOptionMeta — Winner reference for a single sort criterion. The `offerId` matches a `journeys[].offers[].offerId` in the same response, allowing fast lookup of the winning offer's full details.
        - `journeyKey` string, nullable — The journeyKey of the winning journey for this sort criterion
        - `offerId` string, nullable — The offerId of the winning offer (matches `journeys[].offers[].offerId`). Present for offer-centric criteria (best, price); may be null for journey-centric criteria (duration, stops).
        - `price` number — Display total price of the winning offer (with margin applied)
        - `currency` string — Currency code of the price (e.g. USD, EUR)
      - `stops` FlightSortOptionMeta — Winner reference for a single sort criterion. The `offerId` matches a `journeys[].offers[].offerId` in the same response, allowing fast lookup of the winning offer's full details.
        - `journeyKey` string, nullable — The journeyKey of the winning journey for this sort criterion
        - `offerId` string, nullable — The offerId of the winning offer (matches `journeys[].offers[].offerId`). Present for offer-centric criteria (best, price); may be null for journey-centric criteria (duration, stops).
        - `price` number — Display total price of the winning offer (with margin applied)
        - `currency` string — Currency code of the price (e.g. USD, EUR)

## Other responses

- `400` — Bad request — missing or invalid search parameters
- `401` — Unauthorized
- `502` — Provider error
- `503` — Service unavailable

---

[API](https://skmtc.net/liteapi/apis/api-search.md) · [All operations](https://skmtc.net/liteapi/apis/api-search/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/liteapi/api-search/versions/315ba2a4dcf4/schema)