> **For AI agents:** this page is a focused, LLM-optimized view of a
> single Fiber AI operation. Before calling it, fetch the routing
> instructions at [`https://api.fiber.ai/llms.txt`](https://api.fiber.ai/llms.txt) and the full operation
> index at [`https://api.fiber.ai/ai-docs/index.md`](https://api.fiber.ai/ai-docs/index.md).

# flightDeals

`POST /v1/flights/deals`

**Tags:** `Market intelligence`

Search flight deals

**Endpoint:** `https://api.fiber.ai/v1/flights/deals`

## Description

Returns cheap round-trip flight deals from a given departure location, ranked by how much cheaper they are than usual. Dates and destinations are chosen per deal; use flight search when you already know the route and dates.

⚡ Rate limit: 120 requests per 1 minute

💰 Cost: 2 credits per request ⓘ

## Request body (JSON Schema)

```json
{
  "type": "object",
  "properties": {
    "apiKey": {
      "type": "string",
      "description": "Your Fiber API key"
    },
    "departureAirports": {
      "type": "string",
      "description": "Where to find deals from. Accepts a single 3-letter IATA airport code (e.g. 'JFK'), an X- metro alias that covers every airport in a metro area (e.g. 'X-NYC' — call GET /v1/enums/flight-regions for the full list), or a Freebase ID — a stable location identifier beginning with '/m/' or '/g/' (e.g. '/m/02_286' for New York City), listed as `freebaseId` in GET /v1/enums/flight-regions. Comma-separated airport lists are not supported; use an X- alias instead. Case-insensitive except Freebase IDs."
    },
    "currencyCode": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "default": "USD",
      "description": "ISO 4217 currency code for prices in the response (e.g. 'EUR', 'GBP', 'CAD'). Case-insensitive. Defaults to USD."
    },
    "languageCode": {
      "type": "string",
      "pattern": "^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$",
      "default": "en",
      "description": "Language for destination names and descriptions. Pass a BCP-47 language tag such as 'en', 'en-US', 'pt-BR', 'zh-CN', 'ja', 'ko', 'fr', 'de', 'es'. Does not change which deals are returned. Defaults to en."
    },
    "discovery": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "mode": {
              "type": "string",
              "enum": [
                "freeText"
              ]
            },
            "freeText": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200,
              "description": "Free-text description of the destinations to surface (e.g. 'beaches and islands', 'ski towns in the Alps')."
            }
          },
          "required": [
            "mode",
            "freeText"
          ],
          "additionalProperties": false
        },
        {
          "type": "object",
          "properties": {
            "mode": {
              "type": "string",
              "enum": [
                "filters"
              ]
            },
            "maxPrice": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 1,
              "description": "Maximum round-trip price in the requested currency. Omit for no cap."
            },
            "maxStops": {
              "type": [
                "integer",
                "null"
              ],
              "minimum": 0,
              "maximum": 2,
              "description": "Maximum number of stops allowed. 0 = nonstop only, 1 = one stop or fewer, 2 = two stops or fewer. Omit to allow any number of stops."
            },
            "travelClass": {
              "type": [
                "string",
                "null"
              ],
              "enum": [
                "economy",
                "premiumEconomy",
                "business",
                "first",
                null
              ],
              "description": "Preferred cabin class. Omit to consider flights across all cabin classes."
            },
            "airlines": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "include": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "string"
                  },
                  "description": "Only return deals operated or marketed by these airlines. Pass 2-letter IATA airline codes (e.g. 'UA' for United, 'AA' for American, 'DL' for Delta). Case-insensitive."
                }
              },
              "description": "Filter by airline. By default all airlines are considered. If you pass 'include', only deals from those airlines are returned."
            }
          },
          "required": [
            "mode"
          ],
          "additionalProperties": false
        },
        {
          "type": "null"
        }
      ],
      "description": "How to narrow the deals. Omit to return the cheapest round-trip deals from the departure location. Use the `freeText` mode to describe the kind of destinations you want in plain language (e.g. 'beaches and islands'); use the `filters` mode for precise constraints on price, stops, cabin class, or airline. Provide exactly one mode — they cannot be combined."
    }
  },
  "required": [
    "apiKey",
    "departureAirports"
  ]
}
```

## Response — success (JSON Schema)

```json
{
  "type": "object",
  "properties": {
    "output": {
      "type": "object",
      "properties": {
        "deals": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "destination": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Destination city or place name."
                  },
                  "freebaseId": {
                    "type": "string",
                    "description": "Stable location identifier (Freebase ID) for this destination, beginning with '/m/' or '/g/' (e.g. '/m/0_vn7'). Pass as `departureAirports` or `arrivalAirports` in POST /v1/flights/search. Always present on returned deals."
                  },
                  "countryCode": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "ISO 3166-1 alpha-3 country code (e.g. 'USA', 'GBR')."
                  },
                  "iataCode": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "IATA code of the destination airport (e.g. 'TYS')."
                  },
                  "tagline": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Short highlight of the destination."
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Longer destination description."
                  },
                  "thumbnailUrl": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Thumbnail image URL for the destination."
                  }
                },
                "required": [
                  "name",
                  "freebaseId"
                ]
              },
              "departureIataCode": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "IATA code of the airport this deal departs from. When `departureAirports` covers a metro, this is the specific airport the deal uses."
              },
              "outboundDate": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Outbound date of the cheapest itinerary (YYYY-MM-DD)."
              },
              "returnDate": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Return date of the cheapest itinerary (YYYY-MM-DD)."
              },
              "tripLengthDays": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Length of the trip in whole days."
              },
              "price": {
                "type": "integer",
                "description": "Deal price in whole currency units."
              },
              "typicalPrice": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Typical price for a similar trip in whole currency units."
              },
              "savingsAmount": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Amount cheaper than the typical price, in whole currency units."
              },
              "savingsPercentage": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 0,
                "maximum": 100,
                "description": "Percent cheaper than the typical price, from 0 to 100."
              },
              "stopCount": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Number of stops on the outbound itinerary."
              },
              "durationMinutes": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "Total outbound flight duration in minutes."
              },
              "airlineName": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Airline operating the itinerary. Null when the itinerary has no single operating airline."
              },
              "airlineCode": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "IATA airline designator (e.g. 'UA')."
              },
              "bookingUrl": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "URL to view and book this itinerary."
              }
            },
            "required": [
              "destination",
              "price"
            ]
          },
          "description": "Cheap round-trip deals from the departure location, ranked by savings versus the typical price. Empty when none match the request."
        },
        "currencyCode": {
          "type": "string",
          "pattern": "^[A-Z]{3}$",
          "description": "ISO 4217 currency code for prices in this response (e.g. 'USD', 'EUR', 'GBP')."
        }
      },
      "required": [
        "deals",
        "currencyCode"
      ]
    },
    "chargeInfo": {
      "oneOf": [
        {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "enum": [
                "charged-now"
              ]
            },
            "creditsCharged": {
              "type": "number"
            },
            "lowCreditAlert": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "getMoreCreditsUrl": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL to top up credits or restart billing cycle to get fresh credits."
                },
                "message": {
                  "type": "string",
                  "description": "Human-readable credits warning."
                },
                "availableCredits": {
                  "type": "number",
                  "description": "Number of credits remaining in the current billing period."
                }
              },
              "required": [
                "getMoreCreditsUrl",
                "message",
                "availableCredits"
              ],
              "description": "Contains a link to get more credits, a warning message, and the remaining credit count."
            }
          },
          "required": [
            "method",
            "creditsCharged"
          ],
          "description": "Credits were charged immediately for this operation"
        },
        {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "enum": [
                "charging-later"
              ]
            },
            "message": {
              "type": "string"
            },
            "lowCreditAlert": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "getMoreCreditsUrl": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL to top up credits or restart billing cycle to get fresh credits."
                },
                "message": {
                  "type": "string",
                  "description": "Human-readable credits warning."
                },
                "availableCredits": {
                  "type": "number",
                  "description": "Number of credits remaining in the current billing period."
                }
              },
              "required": [
                "getMoreCreditsUrl",
                "message",
                "availableCredits"
              ],
              "description": "Contains a link to get more credits, a warning message, and the remaining credit count."
            }
          },
          "required": [
            "method",
            "message"
          ],
          "description": "Credits will be charged after the operation completes"
        },
        {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "enum": [
                "charged-for-async-process"
              ]
            },
            "creditsCharged": {
              "type": "number"
            },
            "message": {
              "type": "string"
            },
            "lowCreditAlert": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "getMoreCreditsUrl": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL to top up credits or restart billing cycle to get fresh credits."
                },
                "message": {
                  "type": "string",
                  "description": "Human-readable credits warning."
                },
                "availableCredits": {
                  "type": "number",
                  "description": "Number of credits remaining in the current billing period."
                }
              },
              "required": [
                "getMoreCreditsUrl",
                "message",
                "availableCredits"
              ],
              "description": "Contains a link to get more credits, a warning message, and the remaining credit count."
            }
          },
          "required": [
            "method",
            "creditsCharged",
            "message"
          ],
          "description": "Credits that were charged for an asynchronous operation"
        },
        {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "enum": [
                "free"
              ]
            },
            "message": {
              "type": "string"
            },
            "lowCreditAlert": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "getMoreCreditsUrl": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL to top up credits or restart billing cycle to get fresh credits."
                },
                "message": {
                  "type": "string",
                  "description": "Human-readable credits warning."
                },
                "availableCredits": {
                  "type": "number",
                  "description": "Number of credits remaining in the current billing period."
                }
              },
              "required": [
                "getMoreCreditsUrl",
                "message",
                "availableCredits"
              ],
              "description": "Contains a link to get more credits, a warning message, and the remaining credit count."
            }
          },
          "required": [
            "method",
            "message"
          ],
          "description": "No credits were charged for this operation"
        },
        {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "enum": [
                "credits-refunded"
              ]
            },
            "creditsRefunded": {
              "type": "number"
            },
            "message": {
              "type": "string"
            },
            "lowCreditAlert": {
              "type": [
                "object",
                "null"
              ],
              "properties": {
                "getMoreCreditsUrl": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL to top up credits or restart billing cycle to get fresh credits."
                },
                "message": {
                  "type": "string",
                  "description": "Human-readable credits warning."
                },
                "availableCredits": {
                  "type": "number",
                  "description": "Number of credits remaining in the current billing period."
                }
              },
              "required": [
                "getMoreCreditsUrl",
                "message",
                "availableCredits"
              ],
              "description": "Contains a link to get more credits, a warning message, and the remaining credit count."
            }
          },
          "required": [
            "method",
            "creditsRefunded",
            "message"
          ],
          "description": "Credits were refunded for this operation"
        }
      ]
    },
    "warnings": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "properties": {
          "field": {
            "type": "string",
            "description": "Full path to extraneous field (e.g., 'searchParams.ExtraField')"
          },
          "message": {
            "type": "string",
            "description": "Warning message"
          }
        },
        "required": [
          "field",
          "message"
        ]
      },
      "description": "Warnings about extraneous fields in request"
    },
    "advice": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "string"
      },
      "description": "Tips, recommendations, and suggestions for using this API effectively."
    }
  },
  "required": [
    "output",
    "chargeInfo"
  ],
  "additionalProperties": false
}
```

---

Canonical JSON: [`https://api.fiber.ai/openapi.json`](https://api.fiber.ai/openapi.json)
Operation index: [`https://api.fiber.ai/ai-docs/index.md`](https://api.fiber.ai/ai-docs/index.md)