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

# Flight price advice (preview)

> Submit a flight with its current price for price advice and a one-day and three-day price outlook.

<Warning>
  This tool is in preview mode. Please contact support to request access.
</Warning>

## Capability

`flight_price_advice` accepts a flight with its current price to help assess whether the price is good and whether it is likely to rise or fall. The response includes outlooks for **1 day and 3 days**; you do not need to choose a waiting period.

For ongoing price tracking, use `price_monitoring`.

| 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)` in the development build |
| CLI | [`jinko flight-price-advice`](/cli/flight-price-advice) in the development build, with the preview enabled |

## Input

All fields below are required. Unknown fields are rejected.

| Field | Type | Meaning |
| - | - | - |
| `origin` | string | Uppercase three-letter IATA city code. No automatic airport-to-city expansion. |
| `destination` | string | Uppercase three-letter IATA city code, different from `origin`. |
| `departure_date` | string | Real `YYYY-MM-DD` date strictly after today's UTC date. |
| `trip_type` | `oneway` or `roundtrip` | Trip shape. |
| `max_stops` | `0`, `1`, or `2` | Maximum stops. |
| `cabin_class` | string | `economy`, `premium_economy`, `business`, or `first`. |
| `current_price` | Amount | One adult's total fare including taxes for the supplied trip, excluding optional paid extras. |

`current_price` uses `{ value, currency, decimal_places }`. Supply a positive integer in the currency's minor units: `{ "value": 32000, "currency": "USD", "decimal_places": 2 }` means **\$320.00**. Use a supported ISO 4217 currency code and its matching decimal precision.

Example request (use a future departure date):

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

## Call the preview

Use development credentials with the development API. Install the development CLI release explicitly:

```bash theme={null}
npm install -g @gojinko/cli@dev
```

Use the development API address and enable the preview command:

```bash theme={null}
JINKO_ENABLE_FLIGHT_PRICE_ADVICE=1 \
JINKO_API_BASE=https://api.dev.gojinko.com \
jinko flight-price-advice \
  --origin NYC --destination LAX --departure-date 2027-06-15 \
  --trip-type oneway --max-stops 0 --cabin-class economy \
  --current-price 32000 --currency USD --decimal-places 2
```

For REST, send the input JSON above to `https://api.dev.gojinko.com/v1/flight_price_advice` using the normal `X-API-Key` header. For MCP, connect to the development Builder endpoint `https://jinko-e90ee33b.alpic.live/mcp` and call `flight_price_advice` with the same JSON arguments. Keep credentials in your environment or credential store.

## Output

The response contains a current-price assessment, a 1-day and 3-day outlook, and a buying recommendation. These results are currently unavailable in the preview, so valid requests return `status: "not_ready"`.

Response excerpt:

```json theme={null}
{
  "schema_version": "2.0",
  "status": "not_ready",
  "reason": "statistics_not_ready",
  "wait_assessment": {
    "status": "unavailable",
    "reason_code": "statistics_not_ready",
    "horizons": [
      {
        "horizon_days": 1,
        "status": "unavailable",
        "reason_code": "statistics_not_ready",
        "direction": null,
        "historical_reference": null
      },
      {
        "horizon_days": 3,
        "status": "unavailable",
        "reason_code": "statistics_not_ready",
        "direction": null,
        "historical_reference": null
      }
    ]
  }
}
```

`horizon_days` identifies the number of days ahead. A `null` direction means no forecast is available. See the [API reference](/api/flight-price-advice) for the complete response schema.