Flexible-date price matrix (one-way or round-trip)

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.

Access

Requires Flights API access and matrix enablement on your account. Matrix search is not enabled by default — contact the LiteAPI support team to request access.

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.

{
  "legs": [
    {
      "origin": "LON",
      "destination": "PAR",
      "date": "2026-08-26"
    }
  ],
  "adults": 1,
  "currency": "EUR",
  "country": "us"
}

{
  "data": [
    {
      "baseOutboundDate": "2026-08-26",
      "baseReturnDate": "2026-09-03",
      "cells": [
        {
          "outboundDate": "2026-08-26",
          "returnDate": "2026-09-03",
          "price": 491.81,
          "currency": "EUR"
        }
      ],
      "cheapest": {
        "outboundDate": "2026-08-26",
        "returnDate": "2026-09-03",
        "price": 491.81,
        "currency": "EUR"
      },
      "currency": "EUR",
      "flexDays": 3
    }
  ]
}