> ## 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.
# Price Monitoring
> Monitor price for a specific origin, destination, and dates pair
Watch a specific route and date pair over time so an agent can act when the fare drops. Use it for prompts like "alert me when Paris to New York for June 17 to 26 goes under €400". Each response includes the current cheapest cached fare and an offer token you can pass to flight\_search when the user decides to book. Cache-only; never triggers a live call.
```text theme={null}
Cache-only flight price snapshot for a fixed origin/destination + dates pair. Intended for scheduled polling, NOT for one-shot shopping or booking.
WHEN TO USE:
- Track the price of a specific route + dates over time and react when it drops (cron / scheduled job).
- Recommended cadence: poll no faster than the cache refresh interval. Polling faster is wasted work.
WHAT IT RETURNS:
- The single cheapest cached itinerary matching the request filters (lowest WITHIN the filter constraints: filters constrain the candidate set, not the win condition).
- An offer_token that remains re-shoppable via flight_search (price_check mode) when the user decides to book.
- status: "ok" (offer present) or "stale" (cache had no matching itinerary: retry later, or call flight_search for a live quote).
WHEN TO USE flight_search INSTEAD:
- The user is ready to book NOW and needs a live quote.
- One-shot exploration where you don't intend to come back.
WHEN TO USE flight_calendar / find_destination INSTEAD:
- Flexible dates or ranges: price_monitoring requires exact departure_date (+ optional exact return_date).
- The user is still exploring and hasn't committed to a specific route to monitor.
CACHE-ONLY CONTRACT:
- This tool NEVER triggers a live connector call. status:"stale" is the correct response when the cache is cold. Do not retry in a tight loop and do not silently fall back to flight_search.
INPUT NOTES:
- Origin / destination: IATA city code preferred (PAR, NYC, LON); pin to airport only when the user actually committed to a specific airport.
- Use the SAME filter set the user has been monitoring against between polls.
```
## Parameters
| Name | Type | Required | Description |
| -------------------------- | ---------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `origin` | `string` | Yes | Origin IATA city code (e.g. PAR, NYC, LON) or airport code (CDG, JFK, LHR). City codes preferred: they cover every airport in the city. |
| `origin_type` | `enum ("city" \| "airport")` | No | How to interpret origin. "city" (default) searches all airports in the city; "airport" pins to one airport. |
| `destination` | `string` | Yes | Destination IATA city code (e.g. MIL, BCN, TYO) or airport code (MXP, BCN, NRT). City codes preferred. |
| `destination_type` | `enum ("city" \| "airport")` | No | How to interpret destination. Same semantics as origin\_type. |
| `departure_date` | `string` | Yes | Single departure date (YYYY-MM-DD). Exactly one date, no arrays or ranges. |
| `return_date` | `string` | No | Single return date (YYYY-MM-DD). Omit for one-way. Must be on or after departure\_date. |
| `direct_only` | `boolean` | No | If true, only return non-stop flights. Mirror the upstream filter the user committed to when they started monitoring. |
| `cabin_class` | `enum ("economy" \| "premium_economy" \| "business" \| "first")` | No | Cabin class filter. Omit for economy. |
| `max_price` | `number` | No | Upper bound on the total fare in the requested currency. Lowest-fare semantics are "lowest within the filter constraints": max\_price tightens the candidate set, not the win condition. |
| `include_carriers` | `array` | No | IATA 2-letter marketing carrier codes to include (whitelist). Example: \["AF","KL"]. Use to lock monitoring to specific airlines the user actually flies. |
| `exclude_carriers` | `array` | No | IATA 2-letter marketing carrier codes to exclude (blacklist). Example: \["FR","U2"]. Use to keep airlines the user refuses out of the picture. |
| `traveler_counts` | `object` | No | Traveler counts. Defaults to 1 adult. |
| `traveler_counts.adults` | `integer` | No | Number of adult travelers (12+). |
| `traveler_counts.children` | `integer` | No | Number of child travelers (2-11). |
| `traveler_counts.infants` | `integer` | No | Number of infant travelers (under 2). |
| `locale` | `string` | No | User's BCP 47 locale (e.g. "fr-FR", "en-US"). Inherits from the conversation locale if omitted. |
| `currency` | `string` | No | ISO 4217 currency code (e.g. "EUR", "USD"). Inherits from the conversation if omitted. Must match the currency the user is monitoring against. Switching currencies mid-poll is not what they want. |
## Examples
**Daily poll of PAR → NYC for a date pair:**
```json theme={null}
{
"name": "price_monitoring",
"arguments": {
"origin": "PAR",
"destination": "NYC",
"departure_date": "2026-06-17",
"return_date": "2026-06-26",
"currency": "EUR"
}
}
```
**Constrained poll, direct-only, economy, under €800, Air France or KLM only:**
```json theme={null}
{
"name": "price_monitoring",
"arguments": {
"origin": "PAR",
"destination": "NYC",
"departure_date": "2026-06-17",
"return_date": "2026-06-26",
"direct_only": true,
"cabin_class": "economy",
"max_price": 800,
"include_carriers": ["AF", "KL"],
"currency": "EUR"
}
}
```
The returned `offer_token` is directly re-shoppable via `flight_search` (price\_check mode) when the user is ready to book.