Overview

Search the cheapest fare for each departure (and, on round-trips, return) date combination across a grid of nearby dates — ±flexDays around the dates in your request. Accepts the same legs-based body as POST /flights/rates plus optional flexDays (1–3, default 3).

Supported: one-way (1 leg) or round-trip (2 legs) only. Multi-city (3+ legs) is not supported.

Not supported: top-level origin, destination, departureDate, or returnDate — use legs only.

When to Use

• Flexible-date calendars — price heatmap when the traveller can shift dates
• Cheap-date discovery — find the lowest fare in a ±N day window before a full /flights/rates search
• Round-trip date pairing — compare outbound × return combinations on one grid
• Progressive UI — stream cells over SSE as each underlying search completes

What You Get

• cells — one entry per valid date combination, sorted by (outboundOffset, returnOffset)
• cheapest — globally lowest-priced cell (null when nothing was priced)
• currency — currency of the global cheapest cell
• baseOutboundDate / baseReturnDate — the originally requested dates
• flexDays, roundTrip — grid metadata
• Per-cell price, currency, date offsets, and whether the underlying search was cached or success
• Margined prices — cell price, cheapest, and currency include the authenticated user's rate-search margin (same as /flights/rates)

Key Features

• Probes ±flexDays (1–3) around requested departure and return dates
• Each underlying date pair uses normal provider caching — a later POST /flights/rates for a matrix date is served from warm cache
• SSE: send header Accept: text/event-stream for incremental events: matrix-start (grid skeleton), matrix-chunk (one priced cell), matrix-complete (full sorted grid + cheapest)
• Same global filters, sort, and options as /flights/rates where applicable

Quick Start

Required: legs (1 leg for one-way or 2 for round-trip, each with origin, destination, date), adults (≥ 1), currency

Optional: flexDays (1–3, default 3), country, passenger counts, filters, sort

Round-trip: two legs — outbound then return with optional direction OUTBOUND / INBOUND. One-way: one leg.

After choosing a date pair from the matrix, call POST /flights/rates with legs set to those dates for full offer details.