Search flights

Search available flight offers across every compatible supplier. Results are grouped under suppliers[]: each supplier has its own searchId and its own list of offers.

Permission: Read (a read key is enough; so is a read+write key). Rate group: search, 6,000 requests per minute per key.

What to expect

• Size. A search returns 0.7 MB (one-way, two suppliers) to 14 MB of JSON (a busy round trip with 2,000 offers). Send Accept-Encoding: gzip: the same 695 KB response is 26 KB on the wire. There is no pagination: results.totalOffers always equals the length of results.offers.
• Time. Two to eight seconds, because the response waits for the slowest supplier. To show the first fares after about two seconds, read the results as a stream.
• Partial results are normal. If at least one supplier answers, the status is 200 and the others are listed in failures[]. Only when no supplier answers is the status 503.
• Values are read generously, garbage is refused. A value a real client can send ("2" for a count, premium economy for a cabin, a space between airline codes) is read, with a coerced_value warning when its meaning had to be guessed (Conventions). Only a value that makes no sense is a 400 with a stable code, before any supplier is called.
• Identical searches are merged. Searches with the same parameters that arrive at the same moment from the same agency, environment and currency are merged into one supplier fan-out. Nothing is kept afterwards, and every caller still gets its own requestId and headers and a searchId that works with price_flight.
• Sandbox suppliers. amadeus_aqc_dz_1 (Amadeus Algeria, only for routes that touch Algeria; supports hold, void and flexible dates) and duffel_1 (Duffel, worldwide; instant ticketing only). See Supplier selection.

Request fields

Route

¹ Required unless segments or url is sent. ² A list of segments replaces origin, destination, departure_date and return_date.

The type of the search comes from the route: one segment is ONE_WAY; two segments where the second is the exact reverse of the first (or return_date) is ROUND_TRIP; two segments that are not reverses is OPEN_JAW; three or more is MULTI_CITY.

Several airports can be written "ALG,ORN" or as a list ["ALG","ORN"] (up to five, in origin and destination only: a segment takes one code): the first one is searched and the others are kept as alternatives that a supplier may ignore (Duffel does). Search one airport per request when you need a predictable result.

Passengers and cabin

The cabin you send is lower case; the cabin of each segment in the response is upper case (ECONOMY, PREMIUM_ECONOMY, BUSINESS, FIRST).

Filters

What each supplier enforces. filtersApplied in the response repeats what you asked for, for every supplier, not what the supplier honoured:

Always read the offer itself (pricing, travelerPricing[].fareDetailsBySegment[].includedCheckedBags, conditions) and filter again on your side when a filter is a hard requirement. You can send included_airlines and excluded_airlines together: the excluded codes are taken out of the included list.

Supplier selection

Other fields

Legacy names

These spellings still work. The response says so in warnings (deprecated_field) and in the headers Deprecation and X-FX-Deprecated-Fields. New code should send the name in the second column. If a request holds a legacy name and its replacement with different values (direct and nonstop), the replacement wins and an ignored_field warning names the dropped one.

A key the endpoint does not read at all (a typo, the flat adults, max_stops inside filters) never fails the request: it is ignored and reported as an ignored_field warning.

Examples by category

Minimal request

curl https://api.fx-port.com/api/v1/get_flights \
  -H "Authorization: Bearer fxp_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "origin": "ALG",
  "destination": "CDG",
  "departure_date": "2026-12-15",
  "cabin_class": "economy",
  "passengers": {
    "adults": 1
  }
}'

Response essentials

The example is a trimmed real sandbox response to the request above: the Duffel entry with one non-stop offer (the sandbox airline ZZ is Duffel's test carrier). The other supplier's entry has the same shape. Arrays are cut and the amenities list is shortened; the field tables below describe everything that is not shown.

{
  "environment": "sandbox",
  "success": true,
  "requestId": "54139f32",
  "searchType": "ONE_WAY",
  "flexible": false,
  "processingTime": 2.243,
  "suppliers": [
    {
      "success": true,
      "searchId": "fs_dfx_a3aeaa36-74ad-424b-b88d-e6bdc9a4ba94",
      "supportHold": false,
      "supportVoid": false,
      "voidDeadline": null,
      "filtersApplied": {},
      "warnings": [],
      "meta": {
        "supplierId": "duffel_1",
        "technologyType": "duffel",
        "supplierName": "Duffel",
        "processingTime": 1.34,
        "supplierCurrency": "USD",
        "agencyCurrency": "DZD"
      },
      "results": {
        "totalOffers": 92,
        "supplierCurrency": "USD",
        "agencyCurrency": "DZD",
        "offers": [
          {
            "id": "fx_offer_9ab6d940",
            "type": "flight_offer",
            "supplier": { "id": "duffel_1", "name": "Duffel", "originalId": "off_034q6JKdiQDZ8HIDMFus64" },
            "bookableSeats": null,
            "supportHold": false,
            "supportVoid": false,
            "voidDeadline": null,
            "filtersApplied": {},
            "warnings": [],
            "instantTicketingRequired": false,
            "lastTicketingDate": "2026-11-01",
            "lastTicketingDateTime": "2026-11-01T15:52:40.830072Z",
            "pricing": {
              "supplierCurrency": "USD",
              "agencyCurrency": "DZD",
              "basePrice": 16385.0,
              "taxesAndFees": 5226.2,
              "agencyCommission": 21.62,
              "finalPrice": 21632.82,
              "b2bPrice": 21611.2,
              "additionalServices": []
            },
            "itinerary": [
              {
                "direction": "outbound",
                "duration": "PT2H24M",
                "stops": 0,
                "segments": [
                  {
                    "id": "seg_0000BC0a5iUChSV6Qrz0Co",
                    "departure": {
                      "airportCode": "ALG",
                      "airportName": "Houari Boumediene Airport",
                      "cityName": "Algiers",
                      "countryCode": "DZ",
                      "terminal": "2",
                      "datetime": "2026-12-15T10:50:00",
                      "timeZone": "Africa/Algiers"
                    },
                    "arrival": {
                      "airportCode": "CDG",
                      "airportName": "Paris Charles de Gaulle Airport",
                      "cityName": "Paris",
                      "countryCode": "FR",
                      "terminal": "1",
                      "datetime": "2026-12-15T13:14:00",
                      "timeZone": "Europe/Paris"
                    },
                    "flight": {
                      "carrierCode": "ZZ",
                      "carrierName": "Duffel Airways",
                      "carrierLogoUrl": "https://assets.duffel.com/img/airlines/for-light-background/full-color-logo/ZZ.svg",
                      "flightNumber": "7426",
                      "aircraftCode": null,
                      "aircraftName": null,
                      "operatingCarrier": "ZZ",
                      "operatingCarrierName": "Duffel Airways"
                    },
                    "duration": "PT2H24M",
                    "cabin": "ECONOMY",
                    "bookingClass": null,
                    "fareBasis": "Y20LGTN2",
                    "brandedFare": "BASIC",
                    "brandedFareLabel": "Basic"
                  }
                ],
                "conditions": {
                  "changeBeforeDeparture": { "allowed": false },
                  "refundBeforeDeparture": { "allowed": false }
                }
              }
            ],
            "travelerPricing": [
              {
                "travelerId": "pas_0000BC0a5iH5UE0bmBqWkl",
                "travelerType": "ADULT",
                "fareOption": "STANDARD",
                "price": {
                  "supplierCurrency": "USD",
                  "agencyCurrency": "DZD",
                  "base": 16385.0,
                  "total": 21632.82,
                  "b2bPrice": 21611.2
                },
                "fareDetailsBySegment": [
                  {
                    "segmentId": "seg_0000BC0a5iUChSV6Qrz0Co",
                    "cabin": "ECONOMY",
                    "fareBasis": "Y20LGTN2",
                    "brandedFare": "BASIC",
                    "brandedFareLabel": "Basic",
                    "bookingClass": null,
                    "includedCheckedBags": { "quantity": 1 },
                    "includedCabinBags": { "quantity": 1 },
                    "amenities": [
                      { "description": "WIFI", "isChargeable": true, "amenityType": "WIFI", "amenityProvider": { "name": "BrandedFare" } }
                    ]
                  }
                ]
              }
            ],
            "conditions": {
              "refundBeforeDeparture": { "allowed": false },
              "changeBeforeDeparture": { "allowed": false }
            },
            "fareRules": {
              "exchange": { "allowed": false },
              "refund": { "allowed": false },
              "revalidation": { "allowed": false },
              "supplierCurrency": "USD",
              "agencyCurrency": "DZD"
            },
            "validatingAirline": [{ "code": "ZZ", "name": "Duffel Airways" }]
          }
        ]
      },
      "exchangeRate": 250.0
    }
  ],
  "summary": { "totalSuppliers": 2, "successfulSuppliers": 2, "failedSuppliers": 0, "totalOffers": 158 }
}

Names: next to the keys you feed back into the next calls the response adds snake_case twins with the same value. At the top level: request_id, processing_time, search_type. In each supplier entry: search_id, support_hold, support_void, void_deadline, exchange_rate, filters_applied, and meta.supplier_id, meta.supplier_name, meta.processing_time. In each offer: offer_id (next to id), support_hold, support_void, void_deadline, pricing.base_price, pricing.taxes_and_fees, pricing.agency_commission, pricing.final_price, pricing.b2b_price, and passenger_id and passenger_type in each travelerPricing entry. Add ?naming=snake to get every key in snake_case. See Conventions and naming.

Top-level response fields

suppliers[n] fields

offers[n] fields

itinerary[n] and segments[n] fields

travelerPricing[n] fields

The entries are grouped by type (adults, then seniors, children ...), not in the order you would list the travelers: a request has no passenger order. Each traveler's price.total adds up to the offer's pricing.finalPrice.

Save these values

Streaming

Add ?stream=true (or send Accept: text/event-stream) to receive the same search as server-sent events: a first event after about half a second, the first offers after about two seconds, and the rest as each supplier answers. See Streaming search results for the events, the merge rules, the client code in nine languages and the Cloudflare notes. Keep at most 4 streams open at the same time for one API key.

Errors

The error body is described in Errors. Branch on errors[0].code.

Invalid input is refused before any supplier is called, so it never costs a supplier request and never counts against a supplier. A supplier that keeps failing is skipped for a short while and listed in failures[] with the cause supplier_temporarily_unavailable; the others still answer. A supplier whose capacity is full for a moment is listed the same way with the cause supplier_busy while the others answer; only when every supplier is busy is the whole search refused with 503 supplier_busy and Retry-After. service_overloaded works like supplier_busy when FX-Port itself was too busy to prepare a supplier's results (one supplier: failures[]; all of them: 503). Neither makes FX-Port skip the supplier for later searches.

Test it in the sandbox

Related

• Price a flight offer: the required next step.
• Streaming search results and Flexible-date search.
• API reference: Search flights and the Flight offer object.