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

# Flight price advice (preview)

> Compare your flight's price with typical fares and see forecasted prices for the next 1–3 days.

<Warning>
  This tool is in preview. Contact support to enable preview access for your account.
</Warning>

`flight_price_advice` accepts a flight with its current price. It compares that fare with
typical fares for comparable flights and provides price forecasts for the next 1 and 3 days,
including the forecasted price and estimated probabilities of an increase, decrease, or no change.
The tool does not search for a flight, fetch a live quote, monitor a fare, or book.

| Surface | Entry point |
| - | - |
| MCP | [`flight_price_advice`](/tools/flight-price-advice) on the development Builder MCP |
| REST | [`POST /v1/flight_price_advice`](/api/flight-price-advice) on the development API |
| TypeScript SDK | `tools.flightPriceAdvice(input)` with preview opt-in |
| CLI | [`jinko flight-price-advice`](/cli/flight-price-advice) with preview opt-in |

## Input

Supply uppercase three-letter IATA city codes, a future departure date, trip and cabin classes,
and one adult's total fare including tax but excluding optional paid extras. `current_price.value`
is an integer in minor units, so `{ "value": 22840, "currency": "USD", "decimal_places": 2 }`
means USD 228.40.

`stops` is the actual number of connections (`0`, `1`, or `2`). It is optional: omit it when the
number is unknown. Sending `null` is invalid. There is no `max_stops` or `wait_days` input because
the request describes an already selected flight and the response always includes both horizons.

```json theme={null}
{
  "origin": "NYC",
  "destination": "LAX",
  "departure_date": "2027-06-15",
  "trip_type": "oneway",
  "stops": 0,
  "cabin_class": "economy",
  "current_price": { "value": 22840, "currency": "USD", "decimal_places": 2 }
}
```

Initial numeric coverage is one adult, one-way, nonstop, and USD. Other structurally valid
currencies, trip types, and stop counts are accepted; they return a reasoned `unavailable` result
when statistics do not cover them.

## Output

The schema 3.2 response has four possible statuses: `available`, `partial`, `unavailable`, and
`not_ready`.

| Field | Meaning |
| - | - |
| `price_assessment` | How the supplied fare compares with typical prices: label, typical price and range, and percentile. |
| `wait_assessment` | A 1-day and 3-day price forecast with forecasted prices and estimated increase, decrease, and unchanged probabilities. |
| `recommendation` | A structured action, policy basis, and deterministic summary that can be displayed without an LLM. |

Each available forecast includes `forecasted_price` and three estimated probabilities, ranging
from 0 to 1 and summing to 1. Changes within ±1% count as unchanged. When a forecast is
unavailable, `forecasted_price` is `null` and the response explains why. When neither assessment
is available, the response gives no booking recommendation.

### Example price forecast

This example shows selected fields using prices and probabilities from an evaluation at
`2026-09-08T09:29:04Z` for departure on `2026-09-26`. The forecasted price after
3 days is USD 227.57, compared with the supplied fare of USD 228.40. These forecasts describe
prices estimated at that evaluation time.

```json theme={null}
{
  "schema_version": "3.2",
  "status": "available",
  "summary": "This fare is typical for comparable flights. The forecasted price in 3 days is USD 227.57, below the current fare of USD 228.40; waiting is recommended.",
  "context": {
    "evaluated_at": "2026-09-08T09:29:04Z",
    "current_price": { "value": 22840, "currency": "USD", "decimal_places": 2 }
  },
  "price_assessment": {
    "status": "available",
    "label": "typical",
    "typical_price": { "value": 21840, "currency": "USD", "decimal_places": 2 },
    "typical_range": {
      "low": { "value": 20839, "currency": "USD", "decimal_places": 2 },
      "high": { "value": 25281, "currency": "USD", "decimal_places": 2 }
    },
    "percentile": 61.702127659574465,
    "difference_pct": 4.578754578754585
  },
  "wait_assessment": {
    "status": "available",
    "horizons": [
      {
        "horizon_days": 1,
        "direction": "unchanged",
        "forecasted_price": { "value": 23061, "currency": "USD", "decimal_places": 2 },
        "probabilities": {
          "increase": 0.27918781725888325,
          "decrease": 0.25761421319796957,
          "unchanged": 0.4631979695431472
        }
      },
      {
        "horizon_days": 3,
        "direction": "increase",
        "forecasted_price": { "value": 22757, "currency": "USD", "decimal_places": 2 },
        "probabilities": {
          "increase": 0.37913223140495866,
          "decrease": 0.3243801652892562,
          "unchanged": 0.2964876033057851
        }
      }
    ]
  },
  "recommendation": {
    "action": "wait",
    "basis": {
      "policy": "expected_fare",
      "price_label": "typical",
      "selected_horizon_days": 3,
      "wait_direction": "decrease"
    },
    "summary": "The forecasted price in 3 days is USD 227.57, below the current fare of USD 228.40; waiting is recommended."
  }
}
```

`horizon_days` identifies how many days ahead the forecast applies. `forecasted_price` gives
the estimated fare at that horizon. A lower forecasted price can support waiting even when
an increase is the most likely direction. Use the structured fields for application logic and
the summary for display.


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