# Flight Award Availability Scraper — Miles, Taxes & Cabins (`khadinakbar/flight-award-availability-scraper`) Actor

Scrape airline award availability — miles, taxes, and cabin seats — from Flightpoints and Roame for any origin/destination and loyalty program. HTTP-only, cookieless, MCP-ready for travel agents and miles planners.

- **URL**: https://apify.com/khadinakbar/flight-award-availability-scraper.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** Travel, AI, MCP servers
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 award itineraries

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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 Award Availability Scraper

Miles planners, transfer-bonus analysts, and AI travel agents use this Actor to extract award availability **dataset** rows — miles, taxes/surcharges, cabin seats, stops, and loyalty program metadata — for a caller-supplied origin, destination, and date window from public Flightpoints explore calendars and Roame GraphQL search. HTTP-only and cookieless; designed for structured redeemable-award research rather than airline login or booking.

### Best fit for this Actor

- Compare economy, premium, business, or first awards on a known O\&D.
- Filter by program slug or code (for example `american` / `AA`, or Flying Blue `AF/KL`).
- Expand major hubs when origin or destination is left empty for a bounded hub scan.
- Best fit when you need redeemable miles quotes; for paid cash fares and schedule shopping on the same O\&D, start with or continue with the sibling cash-fare Actor linked under Connect the workflow.

### Practical scenario

A miles planner sets origins `JFK`, destinations `LHR`, cabin `business`, and a single forward departure date, with `maxItems` at `20`. The run returns dual-source award rows: Flightpoints cabin blocks with miles/taxes/seats and Roame fares with flight numbers when present. The planner sorts by miles then taxes, then re-checks the winning program on the airline site before transferring points.

### Quick start input

```json
{
  "origins": ["JFK"],
  "destinations": ["LHR"],
  "startDate": "YYYY-MM-DD",
  "endDate": "YYYY-MM-DD",
  "cabin": "business",
  "sources": ["flightpoints", "roame"],
  "maxItems": 20,
  "maxConcurrency": 3
}
```

Leave dates empty to search about a month ahead. The forward window caps at sixty days from today.

### Input reference

| Field | What it controls |
| --- | --- |
| `origins[]` / `destinations[]` | IATA codes. Empty side expands major hubs. |
| `startDate` / `endDate` / `departureDate` | Departure window (`YYYY-MM-DD`). |
| `routes[]` | Explicit `{origin,destination,departureDate}` jobs. |
| `cabin` | `economy` | `premium` | `business` | `first` |
| `issuers[]` | Program slug or code filter |
| `sources[]` | Default `["flightpoints","roame"]` |
| `directOnly` | Keep nonstop awards only |
| `maxItems` | Cap billed rows (default 100; quality prefill 20) |
| `maxConcurrency` | Parallel searches (default 3) |
| `proxyConfiguration` | Optional Apify Proxy |

### What data you receive

One dataset item is one award itinerary. Flightpoints may fill multiple cabins on one row; Roame is typically one cabin per fare.

```json
{
  "source": "flightpoints",
  "origin": "JFK",
  "destination": "LHR",
  "departureDate": "YYYY-MM-DD",
  "program": "AA",
  "programName": "AAdvantage",
  "issuer": "american",
  "cabins": {
    "business": { "miles": 57500, "taxes": 733.5, "seats": 2, "stops": 0, "airlines": ["BA", "AA"] }
  },
  "scrapedAt": "ISO-8601 timestamp"
}
```

| Field | Meaning |
| --- | --- |
| `source` | `flightpoints` or `roame` |
| `program` / `issuer` | Loyalty program code and slug |
| `cabins` | Per-cabin miles, taxes, seats, stops, airlines |
| `flightNumbers` / `durationMinutes` | Present when Roame provides them |
| `lastSeen` / `scrapedAt` | Provider freshness and scrape time |

Download JSON, CSV, or Excel from the run dataset. Key-value `OUTPUT` / `RUN_SUMMARY` use outcomes `COMPLETE`, `PARTIAL`, `VALID_EMPTY`, `INVALID_INPUT`, `UPSTREAM_FAILED`, or `CONFIG_ERROR`.

### Use through the API

```bash
curl "https://api.apify.com/v2/acts/khadinakbar~flight-award-availability-scraper/runs?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"origins":["JFK"],"destinations":["LHR"],"cabin":"business","maxItems":20,"sources":["flightpoints","roame"]}'
```

Read rows from the run `defaultDatasetId` after status is SUCCEEDED. Check key-value `OUTPUT.outcome` for the terminal contract above.

### Use with AI agents through Apify MCP

> Search award availability JFK to LHR in business cabin. Return miles, taxes, seats, and stops. Cap at twenty rows. Sources: flightpoints and roame. Prefer American and Flying Blue when both appear.

Inspect `OUTPUT.outcome`, keep `origin`/`destination`/`departureDate`/`program` as provenance, and keep `maxItems` small. Client setup: <https://mcp.apify.com>.

### Connect the workflow

This Actor is designed as a focused standalone workflow for redeemable award space. When you also need paid cash fares on the same O\&D, then pass that route into [Kayak Flights Scraper](https://apify.com/khadinakbar/kayak-flights-scraper) for schedule and cash-price context beside miles.

Keep award rows here for miles planning only; hotel stays belong on a dedicated lodging Actor such as [Airbnb Scraper](https://apify.com/khadinakbar/airbnb-scraper) when you need listing inventory after the flight award is chosen.

### Pricing

This Actor uses Pay per event plus Apify platform usage. Open the live Pricing tab for current event details, and use Apify's run cost controls to keep the workflow aligned with your budget.

- `apify-actor-start`: $0.00005 per run
- `award-itinerary`: $0.003 per saved award row

A quality prefill that returns twenty itineraries bills one start event plus twenty `award-itinerary` events. Empty successful searches (`VALID_EMPTY`) and invalid input charge no itinerary events.

### Best results

- Start with one O\&D and one date; expand hubs after a successful single-route run.
- Keep `maxConcurrency` at two or three so Roame polling stays stable.
- Use issuer code `AF/KL` for Flying Blue (URL-encoded automatically).
- Treat provider `lastSeen` as a freshness hint and re-check before transferring points.

### Design note

In my testing, anonymous Flightpoints explore calendars were the reliable bulk source, while authenticated Flightpoints search and MCP stayed gated — so this Actor stays on explore plus Roame initiate/poll. Roame needs a short poll loop until the search is mostly complete; that dual-path design is why rows carry an explicit `source` field instead of pretending one upstream owns every award.

### Responsible use

Use public award-search data for personal research and planning. Follow airline program rules, Flightpoints and Roame terms, and applicable law. Award space changes constantly; verify on the airline site before transferring points or booking.

Flightpoints is a trademark of its respective owner. This independent Actor is not affiliated with, associated with, or endorsed by Flightpoints. Roame is a trademark of its respective owner. This independent Actor is not affiliated with, associated with, or endorsed by Roame. American Airlines and AAdvantage are trademarks of American Airlines, Inc. This independent Actor is not affiliated with, associated with, or endorsed by American Airlines, Inc.

# Actor input Schema

## `origins` (type: `array`):

IATA origin codes (e.g. JFK). When empty and destinations are set, expands across major hubs. Pair with destinations or use routes\[].

## `destinations` (type: `array`):

IATA destination codes (e.g. LHR). When empty and origins are set, expands across major hubs.

## `startDate` (type: `string`):

First departure date (YYYY-MM-DD). Defaults to ~30 days from today when empty. Max 60 days forward from today.

## `endDate` (type: `string`):

Last departure date (YYYY-MM-DD). Defaults to startDate when empty. Window capped at 60 days from today.

## `departureDate` (type: `string`):

Shortcut for a single-day search (YYYY-MM-DD). Overrides startDate/endDate when set.

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

Optional list of {origin, destination, departureDate} routes. When set, these are searched in addition to origins×destinations.

## `cabin` (type: `string`):

Keep only awards with availability in this cabin. Empty = all cabins.

## `issuers` (type: `array`):

Filter by program slug (american, united, flyingblue, aeroplan) or code (AA, UA, AF/KL). Empty = all live programs.

## `sources` (type: `array`):

Which providers to query: flightpoints (primary explore calendar) and/or roame (live GraphQL). Default both. Unknown values are ignored.

## `searchClass` (type: `string`):

Roame GraphQL searchClass override. Mapped from cabin when empty: economy→ECON, premium→PREM, business/first→ANY.

## `daysAround` (type: `integer`):

Roame daysAround flexibility (0 = exact date). Usually leave at 0; Flightpoints filters dates client-side.

## `directOnly` (type: `boolean`):

When true, keep only Flightpoints rows where cabin stops === 0. Roame filters numStops === 0.

## `maxItems` (type: `integer`):

Hard cap on billed dataset rows. Quality prefill uses 20.

## `maxConcurrency` (type: `integer`):

Parallel route/source searches. Keep low to respect Roame rate limits.

## `proxyConfiguration` (type: `object`):

Optional Apify Proxy. Direct HTTPS usually works for Flightpoints and Roame.

## Actor input object example

```json
{
  "origins": [
    "JFK"
  ],
  "destinations": [
    "LHR"
  ],
  "startDate": "2026-10-19",
  "endDate": "2026-10-19",
  "departureDate": "2026-10-19",
  "cabin": "business",
  "sources": [
    "flightpoints",
    "roame"
  ],
  "searchClass": "",
  "daysAround": 0,
  "directOnly": false,
  "maxItems": 20,
  "maxConcurrency": 3,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

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

Dataset items with miles, taxes, cabins, program, and route fields.

## `summary` (type: `string`):

OUTPUT record with outcome, itemsPushed, source stats, and billing counters.

## `runSummary` (type: `string`):

Machine-readable RUN\_SUMMARY mirroring OUTPUT.

# 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 = {
    "origins": [
        "JFK"
    ],
    "destinations": [
        "LHR"
    ],
    "cabin": "business",
    "sources": [
        "flightpoints",
        "roame"
    ],
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/flight-award-availability-scraper").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 = {
    "origins": ["JFK"],
    "destinations": ["LHR"],
    "cabin": "business",
    "sources": [
        "flightpoints",
        "roame",
    ],
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/flight-award-availability-scraper").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 '{
  "origins": [
    "JFK"
  ],
  "destinations": [
    "LHR"
  ],
  "cabin": "business",
  "sources": [
    "flightpoints",
    "roame"
  ],
  "maxItems": 20
}' |
apify call khadinakbar/flight-award-availability-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,khadinakbar/flight-award-availability-scraper"
        }
    }
}
```

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/XWRewC1KIkdiINdXu/builds/L5xX5FOeMZvw2s431/openapi.json