---
title: "Quick price discovery for up to 100 destinations — counts as 1 search"
method: POST
path: "/flights/discover"
tags: ["flights"]
---

# Quick price discovery for up to 100 destinations — counts as 1 search

`POST /flights/discover`

## Request

- Base URL: `https://letsfg.co/developers/api/v1`
- URL: `https://letsfg.co/developers/api/v1/flights/discover`
- Auth: API key in header `X-API-Key`

Two modes, selected by the `same_day` flag — pick the one that matches what you need:

**Default (`same_day` omitted/false):** indicative prices from a fast lightweight source across up to 100 destinations, ~2–5 seconds, counted as one search for the whole batch - and not at all when every price was already cached. Response has `price`/`found` only — no offer detail, no `booking_url`. Treat as a ranking signal, not a bookable fare. Setting `return_from` here changes it from one-way to round-trip pricing, but still returns no offer or link — `same_day` is the only switch that adds one.

**`same_day: true`:** real per-destination same-day round-trip search (real flight times, cross-carrier pairing). Slower per destination — keep batches to roughly 10–20 destinations. Counted as one search per call. Each found result includes `outbound`/`inbound` with real times and a `booking_url` per leg, and the price matches what POST /flights/search and checkout will show for that same-day trip.

**If your itinerary is a same-day round trip and you want an accurate, bookable result directly from discover, use `same_day: true` instead of the default mode.** Otherwise, use default mode to rank destinations cheaply, then confirm the winner with a full POST /flights/search call:
1. POST /flights/discover (default mode) → rank up to 100 destinations, counts as 1 search, ~3 seconds
2. User picks a destination
3. POST /flights/search on that destination → live prices + booking, counts as 1 search, 60–90 seconds

## Request body

- DiscoverRequest: Two modes, selected by `same_day`. Default (`same_day` omitted or false): fast indicative price screening across up to 100 destinations from a lightweight data source — no offer detail, no booking_url, treat as a ranking signal only. `same_day: true`: real per-destination round-trip search (same-day out-and-back) with actual flight times and a bookable `booking_url` per leg — slower per destination, so capped lower, but the price you see is the price `/flights/search` and checkout will show. If you need an accurate, linkable result and your itinerary fits a same-day round trip, prefer `same_day: true` over the default mode.
  - `origin` string, required: Departure IATA code (e.g. JFK).
  - `destinations` string[], required: 1–100 destination IATA codes to price-check (default mode). same_day mode is slower per destination — keep batches small (roughly 10–20) to avoid timeouts.
  - `date_from` string, date, required
  - `return_from` string, date: Default mode only: return date for a round-trip indicative price (omit for one-way). Has no effect when same_day is true — same-day mode always returns same-day out-and-back and does not add booking_url/offer detail to default mode.
  - `currency` string
  - `same_day` boolean: true = real same-day round-trip search per destination, with actual offers and booking_url. false/omitted = fast indicative price-only screening, no offer, no link. This is the only switch that controls whether the response includes a bookable offer — return_from does not.
  - `min_hours_at_destination` integer: same_day mode only: minimum hours between landing and the return departure.
  - `max_return_hour` integer, nullable: same_day mode only: latest local hour the return may land the next day (e.g. 2 = home by 2 AM).
  - `max_total_price` number, nullable: same_day mode only: drop destinations whose round-trip total exceeds this price.
  - `adults` integer: same_day mode only: number of adult passengers to check seat availability for. Ignored in default mode. Note: Kiwi (the same_day price source) prices per person regardless of this value, and its generated booking_url currently pre-fills only 1 passenger even when adults > 1 — a limitation of the upstream provider, not this API.
  - `departure_time_from` string: Earliest outbound departure HH:MM.
  - `departure_time_to` string: Latest outbound departure HH:MM.

## Response `200`

Indicative prices for all destinations, sorted cheapest-first.

- DiscoverResponse
  - `origin` string
  - `date_from` string
  - `currency` string
  - `results` object[]: Sorted cheapest-first. Unfound destinations appear last. outbound/inbound/booking_url/hours_at_destination are present only when the request had same_day: true.
    - `destination` string
    - `price` number, nullable: Indicative price (default mode) or real round-trip total (same_day mode). null if no data found.
    - `currency` string
    - `found` boolean
    - `hours_at_destination` number: same_day mode only.
    - `outbound` DiscoverLegOffer: same_day mode only: one leg (outbound or inbound) of the round trip.
      - `depart` string, date-time
      - `arrive` string, date-time
      - `airline` string
      - `stops` integer
      - `price` number
      - `booking_url` string, uri: Direct link to book this leg. Empty string if unavailable.
    - `inbound` DiscoverLegOffer: same_day mode only: one leg (outbound or inbound) of the round trip.
      - `depart` string, date-time
      - `arrive` string, date-time
      - `airline` string
      - `stops` integer
      - `price` number
      - `booking_url` string, uri: Direct link to book this leg. Empty string if unavailable.
  - `summary` object
    - `destinations_checked` integer
    - `prices_found` integer
    - `trips_found` integer: same_day mode only; equal to prices_found.
    - `cheapest_destination` string, nullable
    - `cheapest_price` number, nullable
  - `data_note` string: Explains the pricing source for this response — differs by mode.
  - `degraded` boolean: same_day mode only: true if the upstream search was shedding load and no charge was made.
  - `billed_as` string

## Other responses

- `402`: Prepaid balance empty or payment method missing.

---

[API](https://skmtc.dev/letsfg/apis/letsfg-public-developer-api.md) · [All operations](https://skmtc.dev/letsfg/apis/letsfg-public-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/letsfg/apis/letsfg-public-developer-api/revisions/516ab6ba1d2e?raw)