> ## Documentation Index
> Fetch the complete documentation index at: https://docs.farelint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search observations

`POST /v1/searches` requires a bearer key, JSON `SearchRequest` and `Idempotency-Key` of 8–128 printable ASCII characters.

Required: `airline`, IATA `origin` and `destination`, ISO `departure_date`, nullable `return_date`, `passengers`, `cabin`, `market`, `language`, `currency`. Passenger arrays model children and infants but enabled pilot capabilities reject them before collection. Optional `max_credits` caps the cost.

Same idempotency key and canonical body returns the original job, including at zero balance. A changed body returns `409`. Replay lasts 90 days; retained expired identities return `410`.

Results cover captured results, not all inventory. Adjacent dates are excluded. A return itinerary price must cover both directions; do not combine independent one-way prices into a return quote.

## AEGEAN nonstop alternatives

Use `airline: "aegean"`, LCA → ATH, one way, one adult, economy, English and EUR. `max_results` accepts 1 or 2. The source provides a bounded price-ordered nonstop shortlist, explicitly labelled `coverage.selection: "nonstop_alternatives"`; it excludes connecting flights. Inspect `price.kind: "cabin_starting_quote"` and the per-offer missing fields before using a quote. Async costs 5 credits and sync 7 under the current provisional rate. See [supported scope](https://docs.farelint.com/airlines.md#supported-search-contexts).

## Premium connecting flights

The same request shape accepts `emirates` and `qatar` for their enabled pilot scope:

```json theme={null}
{
  "airline": "emirates",
  "origin": "LCA",
  "destination": "PVG",
  "departure_date": "2027-04-06",
  "return_date": "2027-04-20",
  "passengers": { "adults": 2, "children": [], "infants": [] },
  "cabin": "economy",
  "market": "CY",
  "language": "en",
  "currency": "EUR",
  "max_results": 2,
  "max_credits": 12
}
```

Select `qatar` for Qatar Airways. Poll the returned job as usual. Inspect `price.scope`, segment `direction`, and completeness before comparing amounts. Premium searches now complete when their requested priced shortlist is fulfilled; see [Airlines and capabilities](https://docs.farelint.com/airlines.md).

Use `POST /v1/searches/async` for the explicit asynchronous route (same source credits and idempotency scope as `/v1/searches`). `POST /v1/searches/sync` waits for the durable job and adds 2 credits. The sync response is the same Job envelope, including result and frozen `credit_quote`. A client disconnect does not cancel an accepted job. Use a fresh idempotency key when changing delivery mode; using the same key for a different mode returns `409`.

Premium searches accept `max_results: 1 | 2`, default 2, for a bounded return shortlist. `coverage.exhaustive` is false. UTC times and full fare rules can remain per-offer unknown while the priced shortlist completes. A bound-only quote or missing requested alternative cannot complete a premium return search.

Full request and response schemas: [current OpenAPI download](https://farelint.com/openapi.json).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.