# Flight Price Watch — Google Flights Fare Alerts (`magnova/flight-price-watch`) Actor

Search Google Flights and watch fares for price drops. Give routes and dates; get structured itineraries — or run in watch mode and receive only fare-drop alerts. Built for AI agents: server-callable, pay per record, no start fee.

- **URL**: https://apify.com/magnova/flight-price-watch.md
- **Developed by:** [Magnova](https://apify.com/magnova) (community)
- **Categories:** Travel, Automation, Developer tools
- **Features:** Limited permissions, Single-tenant, Server interface
- **Stats:** 1 total users, 0 monthly users, 87.5% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.40 / 1,000 flight records

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Flight Price Watch — Google Flights Fare Alerts

Search Google Flights, or **watch a fare and get told only when it drops**.

Give routes and dates and get structured itineraries: airlines, local departure and arrival times, per-leg detail with layovers, total duration, emissions where Google shows them, and the total fare for your passengers. Run the same input in **watch mode** on a schedule and the actor remembers the fares — later runs deliver only the itineraries whose price fell, with the previous price and the drop size, plus an optional alert the first time a route's lowest fare crosses your target price.

Built for AI agents and personal assistants: this actor is a **Server Actor** — call it over plain HTTP with a JSON body and get records back in the response, no run to start and no dataset to poll. It is also available through the Apify MCP server and the official MCP registry listing (search "flight-price-watch").

### What you get

**FLIGHT records** — one per itinerary:

| Field | Meaning |
|---|---|
| `price`, `currency` | Total fare for the searched passengers, as Google Flights shows it at check time |
| `airlines` | Airline names on the itinerary |
| `departAt`, `arriveAt` | Local times of the first departure and last arrival |
| `legs[]` | Per-leg from/to airports and names, local times, `durationMinutes`, aircraft where shown |
| `layovers[]` | Per-connection airport and `durationMinutes` |
| `connections`, `durationMinutes` | Connection count and total trip minutes (in-air + layovers) |
| `emissionsKg`, `emissionsVsTypicalPercent` | Google's emissions estimate, where Google shows it |
| `googleFlightsUrl` | The Google Flights search for this route and dates |
| `flightKey` | Stable identity of the itinerary across watch checks |

In watch mode, FLIGHT records carry a `changeType`:

- `BASELINE` — delivered on a watch's first check (the current list, charged as flight records)
- `PRICE_DROP` — the fare fell since the previous check; adds `previousPrice`, `dropAmount`, `dropPercent` (charged as a price-drop alert)
- `TARGET_HIT` — the route's lowest fare crossed your `targetPrice` (charged as a price-drop alert)

**SUMMARY records** (never charged) close each route: flights found and delivered, current and previous lowest fares in watch mode, check count. **ERROR records** (never charged) carry the route and the reason when one route cannot be searched — one bad route never sinks the run.

### Pricing

Pay per event, **no start fee**:

- **Flight record — $0.002** (SILVER $0.0017, GOLD+ $0.0014): search results and watch baselines
- **Price drop alert — $0.02** (SILVER $0.017, GOLD+ $0.014): PRICE_DROP and TARGET_HIT records

You pay for the drop, not the checking: a watch run where nothing fell delivers only the free SUMMARY and charges nothing. `maxTotalChargeUsd` caps any run's spend.

### Input

| Field | Notes |
|---|---|
| `routes` | Up to 10 × `{origin, destination, departureDate, returnDate?}` — 3-letter IATA codes, dates as YYYY-MM-DD |
| `mode` | `search` (default) or `watch` |
| `cabinClass` | economy, premium_economy, business, first |
| `adults`, `children`, `infantsOnLap` | Up to 9 passengers total |
| `currency` | 3-letter code, default USD |
| `maxResultsPerRoute` | Cheapest-first cap per route, 1–50, default 20 |
| `maxStops` | Optional: 0 = nonstop only, 1, 2 |
| `targetPrice` | Watch mode: one alert when the lowest fare reaches it |
| `minDropPercent`, `minDropAmount` | Watch mode: ignore smaller drops |
| `maxTotalChargeUsd` | Optional hard cap per run |

Example — watch JFK → LAX for a June trip, alert under $150:

```json
{
  "routes": [{"origin": "JFK", "destination": "LAX", "departureDate": "2027-06-15"}],
  "mode": "watch",
  "targetPrice": 150,
  "minDropPercent": 3
}
```

Schedule that input (Apify Schedules, or your own cron calling the API) and each run reports only what changed.

### Server mode (for agents)

POST the same JSON input to the actor's server URL:

```
POST https://magnova--flight-price-watch.apify.actor
Authorization: Bearer <your Apify token>
{"routes": [{"origin": "JFK", "destination": "LAX", "departureDate": "2027-06-15"}], "mode": "watch"}
```

The response carries the records directly: `{"records": [...], "summary": {...}}`. Watch state persists between calls, so an assistant can register a fare watch once and poll it with the same body — it hears back only when there is news. Up to 5 routes per server request.

### Notes and limits

- Round-trip prices are Google's full round-trip fares; the leg detail, times and duration describe the outbound journey.
- Public Google Flights data only, read logged out — no account, no cookies, no booking. This actor finds and watches fares; it does not book.
- Fares are exactly as Google Flights displays them at check time and can change at any time; the booking link is the Google Flights search for the route.
- Google Flights covers roughly the next 330 days; dates beyond that return an ERROR record for that route.
- Searches are paced and retried automatically — Google rate-limits rapid repeats, so a 10-route run takes under a minute.
- A watch is identified by route + dates + cabin + passengers + currency. Change any of them and it starts a fresh baseline.

# Actor input Schema

## `routes` (type: `array`):

Each route: origin and destination as 3-letter IATA airport codes (JFK, LHR, DXB), departureDate as YYYY-MM-DD, and an optional returnDate for round trips. Up to 10 routes per run.

## `mode` (type: `string`):

Search returns every itinerary found now. Watch remembers the fares in the actor's storage: the first watch run returns the current list as a baseline, later runs return only price drops and target hits. Run watch mode on a schedule (or call the server URL) to track a fare.

## `cabinClass` (type: `string`):

The cabin to search and watch.

## `adults` (type: `integer`):

Number of adult passengers (prices are totals for all passengers).

## `children` (type: `integer`):

Number of child passengers.

## `infantsOnLap` (type: `integer`):

Number of infants travelling on an adult's lap.

## `currency` (type: `string`):

3-letter currency code for prices, e.g. USD, EUR, GBP, AED.

## `maxResultsPerRoute` (type: `integer`):

Cheapest-first cap on itineraries delivered per route.

## `maxStops` (type: `integer`):

Optional: 0 = nonstop only, 1 = at most one connection. Leave empty for any.

## `targetPrice` (type: `number`):

Optional, watch mode: get one TARGET_HIT alert the first time the route's lowest fare falls to this price or below (in the chosen currency).

## `minDropPercent` (type: `number`):

Watch mode: ignore drops smaller than this percent.

## `minDropAmount` (type: `number`):

Watch mode: ignore drops smaller than this amount (in the chosen currency).

## `maxTotalChargeUsd` (type: `number`):

A hard stop you control: the run stops delivering once its charged total would pass this amount. Leave empty for no cap.

## Actor input object example

```json
{
  "routes": [
    {
      "origin": "JFK",
      "destination": "LAX",
      "departureDate": "2027-06-15"
    }
  ],
  "mode": "search",
  "cabinClass": "economy",
  "adults": 1,
  "children": 0,
  "infantsOnLap": 0,
  "currency": "USD",
  "maxResultsPerRoute": 20,
  "minDropPercent": 0,
  "maxTotalChargeUsd": 1
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "routes": [
        {
            "origin": "JFK",
            "destination": "LAX",
            "departureDate": "2027-06-15"
        }
    ],
    "mode": "search",
    "cabinClass": "economy",
    "adults": 1,
    "children": 0,
    "infantsOnLap": 0,
    "currency": "USD",
    "maxResultsPerRoute": 20,
    "minDropPercent": 0
};

// Run the Actor and wait for it to finish
const run = await client.actor("magnova/flight-price-watch").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "routes": [{
            "origin": "JFK",
            "destination": "LAX",
            "departureDate": "2027-06-15",
        }],
    "mode": "search",
    "cabinClass": "economy",
    "adults": 1,
    "children": 0,
    "infantsOnLap": 0,
    "currency": "USD",
    "maxResultsPerRoute": 20,
    "minDropPercent": 0,
}

# Run the Actor and wait for it to finish
run = client.actor("magnova/flight-price-watch").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "routes": [
    {
      "origin": "JFK",
      "destination": "LAX",
      "departureDate": "2027-06-15"
    }
  ],
  "mode": "search",
  "cabinClass": "economy",
  "adults": 1,
  "children": 0,
  "infantsOnLap": 0,
  "currency": "USD",
  "maxResultsPerRoute": 20,
  "minDropPercent": 0
}' |
apify call magnova/flight-price-watch --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,magnova/flight-price-watch"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/eGG0ek0O3cOadXuFf/builds/djTsMqwJtIBQYsTmB/openapi.json
