Search flight solutions (SSE stream)

Initiate a flight search and stream normalised solutions back as Server-Sent Events. Each data: event is a JSON-encoded flight solution object whose id is a canonical Mercury UUID (see POST /v1/flights/fares). The stream ends with event: done.

Send presentation: "grouped" on a two-leg (round-trip) itinerary to receive event: outbound-group frames instead — one per physical outbound, each carrying a from-price and its priced return options. See docs/adr/MER-1488-flight-grouped-search.md.

Frame vocabulary (event: names on this stream):

  • solution — one normalised flight solution (default framing).
  • outbound-group — one physical outbound with its priced return options (grouped framing only).
  • done — terminal frame; the stream is exhausted (data: {}).
  • error — terminal frame on failure; data: {"code": ..., "message": ...}.
Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

POST body for /v1/flights/search.

Supports one-way, round-trip, and multi-city itineraries. Trip type is
auto-detected from the number of legs: one leg → one-way, two legs →
round-trip, three or more legs → multi-city.

Per-leg time ranges (departureAfter / departureBefore /
arrivalAfter / arrivalBefore) are enforced by the upstream search
provider via poll-query parameters; Mercury forwards them directly (MER-660).

The mercury/assistant/tools/search_flights/ MCP tool has its own flat
input schema and builds native provider params directly, intentionally
bypassing this type. The two schemas diverge by design — the assistant tool
is a natural-language interface while this type is the structured API
contract.

itinerary
array of objects
required
length between 1 and 10

One leg for one-way, two for round-trip, three or more for multi-city.

Itinerary*
passengers
object

Passenger type counts.

string
enum
Defaults to economy

economy | premium_economy | business | first

Allowed:
enum

Booking profile context. personal for non-business bookings, business for business bookings.

Restrict results to non-stop flights (MER-661). True applies the filter; False or omitted means no constraint.

boolean
Defaults to false

Include airports near the departure airport. Applies only when the origin is a specific airport on a one-way or round-trip search. Omitted or false leaves that side unchanged.

boolean
Defaults to false

Include airports near the destination airport. Applies only when the destination is a specific airport on a one-way or round-trip search. Omitted or false leaves that side unchanged.

0 to 1000000000000

Minimum total price per traveler in the search currency (MER-661).

0 to 1000000000000

Maximum total price per traveler in the search currency (MER-661).

Alternative result framing. grouped folds a round trip's solutions by their shared outbound and streams event: outbound-group frames, each carrying a from-price and its priced return options; omitted (the default) streams the flat event: solution sequence unchanged. Only applies to two-leg (round-trip) itineraries — one-way and multi-city searches stream flat regardless. See docs/adr/MER-1488-flight-grouped-search.md.

Responses

401

Missing or invalid authentication

422

Invalid search parameters

503

Flight search provider unavailable

Language
Credentials
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
text/event-stream