---
title: "Flexible-date price matrix (one-way or round-trip)"
method: POST
path: "/flights/rates/matrix"
tags: ["Flight Search"]
---

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

`POST /flights/rates/matrix`

## 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.

## Request body

- object
  - `legs` object[], required — One leg (one-way) or two legs (round-trip). Multi-city is not supported.
    - `origin` string, required — Origin airport or city IATA code for this leg.
    - `destination` string, required — Destination airport or city IATA code for this leg.
    - `date` string, date, required — Departure date for this leg (YYYY-MM-DD).
    - `direction` 'OUTBOUND' | 'INBOUND' — Leg direction (optional; defaults to OUTBOUND on the provider).
  - `adults` integer, required — Number of adult passengers (≥ 1).
  - `children` integer — Number of child passengers (ages 2-11).
  - `infants` integer — Number of infant passengers (under 2).
  - `currency` string, required — ISO 4217 currency for point of sale and displayed prices.
  - `country` string — ISO country code for point of sale
  - `flexDays` integer — Days before/after requested dates to probe

## Response `200`

Price matrix

- FlightMatrixResponse — Response for POST /flights/rates/matrix.
  - `data` FlightMatrixData[], required — Matrix result sets (one element for this endpoint).
    - `baseOutboundDate` string, date — The originally requested departure date (YYYY-MM-DD).
    - `baseReturnDate` string, date, nullable — The originally requested return date. Null for one-way searches.
    - `cells` FlightMatrixCell[] — One cell per valid date combination, sorted by (outboundOffset, returnOffset).
      - `outboundDate` string, date — Departure date for this cell (YYYY-MM-DD).
      - `outboundOffset` integer — Days from the requested departure date (-flexDays..+flexDays).
      - `returnDate` string, date, nullable — Return date for this cell (YYYY-MM-DD). Null for one-way searches.
      - `returnOffset` integer, nullable — Days from the requested return date (-flexDays..+flexDays). Null for one-way searches.
      - `price` number, float, nullable — Cheapest display total for this date combination (includes rate-search margin). Null when no priced offer was found.
      - `currency` string, nullable — ISO 4217 currency of the cell price. Null when no priced offer was found.
      - `success` boolean — True when the underlying search returned at least one priced offer for this combination.
      - `cached` boolean — True when the underlying search was served from cache.
    - `cheapest` FlightMatrixCell — Cheapest-price summary for a single departure/return date combination.
      - `outboundDate` string, date — Departure date for this cell (YYYY-MM-DD).
      - `outboundOffset` integer — Days from the requested departure date (-flexDays..+flexDays).
      - `returnDate` string, date, nullable — Return date for this cell (YYYY-MM-DD). Null for one-way searches.
      - `returnOffset` integer, nullable — Days from the requested return date (-flexDays..+flexDays). Null for one-way searches.
      - `price` number, float, nullable — Cheapest display total for this date combination (includes rate-search margin). Null when no priced offer was found.
      - `currency` string, nullable — ISO 4217 currency of the cell price. Null when no priced offer was found.
      - `success` boolean — True when the underlying search returned at least one priced offer for this combination.
      - `cached` boolean — True when the underlying search was served from cache.
    - `currency` string, nullable — ISO 4217 currency of the global cheapest cell. Null when nothing was priced.
    - `flexDays` integer — Effective flexibility window applied (1-3).
    - `roundTrip` boolean — True when the request was a round-trip (return dates vary across columns).
    - `totalCells` integer, nullable — Total number of date combinations in the grid. Present on matrix-start SSE events; omitted from the non-streaming JSON response.

## Other responses

- `400` — Bad request — missing or invalid matrix search parameters
- `401` — Unauthorized
- `403` — Forbidden — matrix access not enabled for this account
- `500` — Internal server error

---

[API](https://skmtc.net/liteapi/apis/api-search.md) · [All operations](https://skmtc.net/liteapi/apis/api-search/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/liteapi/api-search/versions/315ba2a4dcf4/schema)