# Flight Status API - OAG Flight Schedules, Airports, Airlines (`nabeelbaghoor/flight-status-schedules-aviation-api`) Actor

Real-time flight status and flight schedules from the OAG API: departure and arrival times, delays, gates, terminals, diversions, aircraft, codeshares and seats by flight number, route or airport, plus airport, airline and aircraft type reference data. Bring your own key.

- **URL**: https://apify.com/nabeelbaghoor/flight-status-schedules-aviation-api.md
- **Developed by:** [Nabeel Hassan](https://apify.com/nabeelbaghoor) (community)
- **Categories:** Travel, Developer tools, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $10.00 / 1,000 flight or schedule record returneds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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 Status API - OAG Flight Schedules, Airports, Airlines

Pull real-time flight status, flight schedules and aviation reference data from the OAG APIs with your own subscription key, and get departure and arrival times, delays, gates, terminals, diversions, aircraft, codeshares, seats, airports, airlines and aircraft types as clean dataset rows.

Works with the official OAG developer APIs on api.oag.com: Flight Info v2 (flight instances with status and seats), Schedules (effective schedules) and the Master Data Locations, Carriers and Equipment APIs. The actor turns flight numbers, routes, airports or codes into deduplicated rows you can download as JSON, CSV or Excel, schedule, or feed into travel apps, disruption alerts, airport dashboards, logistics planning, Google Sheets and AI agents. Bring your own API key.

BYOK, not live-tested: every operation, parameter and enum comes from OAG's published OpenAPI documents on developers.oag.com and its knowledge base, and every route was confirmed to exist on api.oag.com, but the actor has not been run against a live OAG subscription.

### What it does

- **Flight status by flight number**: for each flight such as BA117 or UA2, every flight instance on the dates you choose, with scheduled, estimated and actual gate and runway times (local and UTC), flight state, terminal, gate, baggage belt, delays, diversions, irregular operations, aircraft type and tail number, codeshare partners, distance and on-time performance.
- **Flight search by route, airport or airline**: every flight matching departure airports, arrival airports, airline codes, departure or arrival country, or an aircraft registration. Give one airport for a departures or arrivals board, two for a route.
- **Flight schedules by flight number**: the effective schedule of an IATA flight number, as date ranges and operating days, with times, aircraft, stops and codeshares.
- **Airports and locations**: IATA, ICAO and FAA codes, names, terminals, city, country, coordinates, time zone and daylight saving periods, by code, country or city.
- **Airlines and carriers**: IATA and ICAO codes, legal and display names, alliances, domicile, accounting prefix and whether OAG publishes the airline's schedules.
- **Aircraft types**: IATA, ICAO and FAA type codes, manufacturer, model, engine type and count, body, category and wake turbulence class.
- **Optional extra content**: OAG predicted seats, actual seats and extended schedules (booking classes, meals) on flight rows.
- **Pay only for results**: refused and empty lookups are recorded as a free row that says why, never charged.

### How to get an API key

Sign up on the OAG developer portal (developers.oag.com), pick Flight Info (a Free Tier of 1,000 requests every 30 days is offered) or request a trial or full subscription for the API you need, then copy the primary key from your profile once OAG approves it. Paste it into the API key field. The key is sent only in the Subscription-Key header to api.oag.com and is never logged. Each API (Flight Info, Schedules, Master Data) is its own OAG product, so a key only opens the APIs your subscription covers.

### Input

| Field | Modes | Description |
| --- | --- | --- |
| `mode` | all | `flightStatus`, `flightSearch`, `schedules`, `airports`, `airlines` or `aircraftTypes` |
| `flightNumbers` | flight status, schedules | Flight designators such as BA117, BAW117, U2 8001 |
| `departureDate` | flight modes, schedules | 2026-10-20, a range up to 31 days, or a time window such as 2026-10-20T06:00/2026-10-20T12:00. Empty means today |
| `arrivalDate` | flight modes | Search by local arrival date or window instead |
| `departureAirports`, `arrivalAirports` | flight search | IATA, ICAO or FAA airport codes |
| `carrierCodes` | flight search | IATA or ICAO airline codes |
| `departureCountry`, `arrivalCountry` | flight search | ISO 3166-1 alpha-2 country codes |
| `aircraftRegistration` | flight search | Tail number |
| `includeDiverted` | flight search | Also return flights diverted to the arrival airport |
| `content` | flight modes | Status (default), Seats, ActualSeats, ExtendedSchedules |
| `flightTypes`, `serviceTypes`, `codeshare` | flight modes | Scheduled, Unscheduled or GA; Passenger or Cargo; Operating or Marketing |
| `codeTypes` | flight and reference modes | IATA, ICAO, FAA. Empty lets the actor choose |
| `codes` | reference modes | Airport, airline or aircraft type codes; empty lists everything that matches |
| `countryCodes`, `cityCodes` | airports | Airports by country or by city |
| `names`, `aircraftModels` | airlines, aircraft types | Airline names, manufacturer names, model names (partial match) |
| `publishingCarriersOnly` | airlines | Only airlines whose schedules OAG publishes |
| `maxResults` | all | Row ceiling for the run (default 100) |
| `requestsPerMinute` | all | Pacing, default 60 |
| `apiKey` | all | Your OAG subscription key (or the DATA_API_KEY secret) |

Example: the status of two flights today.

```json
{
    "mode": "flightStatus",
    "flightNumbers": ["BA117", "UA2"],
    "content": ["Status"]
}
```

### Example output

An illustrative flight status row, shaped like OAG's documented Flight Info v2 response (values are an example, not real data). Every field OAG returns is kept; only a few are shown.

```json
{
    "mode": "flightStatus",
    "recordType": "flight",
    "identifier": "BA117",
    "found": true,
    "flightDesignator": "BA117",
    "carrierCode": "BA",
    "departureAirportCode": "LHR",
    "arrivalAirportCode": "JFK",
    "departureLocal": "2026-10-20 08:25",
    "arrivalLocal": "2026-10-20 11:10",
    "departureUtc": "2026-10-20 07:25",
    "arrivalUtc": "2026-10-20 15:10",
    "flightState": "InGate",
    "aircraftTypeCode": "77W",
    "carrier": { "iata": "BA", "icao": "BAW" },
    "flightNumber": 117,
    "departure": { "airport": { "iata": "LHR", "icao": "EGLL" }, "terminal": "5" },
    "arrival": { "airport": { "iata": "JFK", "icao": "KJFK" }, "terminal": "8" },
    "statusDetails": [{
        "state": "InGate",
        "departure": { "gate": "B36", "actualTime": { "outGate": { "local": "2026-10-20T08:31:00", "utc": "2026-10-20T07:31:00" } } },
        "arrival": { "baggage": "4", "actualTime": { "inGate": { "local": "2026-10-20T11:02:00", "utc": "2026-10-20T15:02:00" } } }
    }],
    "scheduleInstanceKey": "example-instance-key",
    "retrievedAt": "2026-10-20T16:00:00.000Z",
    "note": null
}
```

### FAQ

#### What is the OAG API?

OAG Aviation Worldwide is a global flight data provider. Its developer APIs on api.oag.com serve flight schedules and flight status per flight instance (Flight Info), effective schedules (Schedules) and aviation master data for airports, airlines and aircraft (Master Data), authenticated with a subscription key.

#### Do I need my own OAG subscription key?

Yes. This is a bring-your-own-key actor: it calls OAG with your key, under your OAG plan and terms. A missing, rejected or exhausted key ends the run cleanly with a status message that explains what to change, and nothing is charged.

#### How do I get the live status of a flight?

Use Flight status by flight number with the flight designator (BA117) and the date. Keep Status in Extra content to get estimated and actual departure and arrival times, gates, baggage belt, delays, diversions and the flight state.

#### Can I get a departures or arrivals board for an airport?

Yes. Use Flight search with one departure airport for departures, or one arrival airport for arrivals, and a date or time window such as 2026-10-20T06:00/2026-10-20T12:00.

#### How far back and ahead does the data go?

Flight Info takes a date range of at most 31 days per request. OAG updates schedules and status in near real time as carriers send them. Your plan decides which dates and content you can read.

#### What do I pay?

Pay per result: 0.01 USD per flight instance or schedule row, and 0.005 USD per airport, airline or aircraft type row. Refused and empty lookups are never charged. Your OAG subscription is billed separately by OAG: the Free Tier allows 1,000 requests every 30 days, paid tiers charge a fixed fee with a charge per request above the limit, and Seats, Actual seats and Extended schedules may cost extra. Each page of up to 1000 rows is one OAG request.

#### What happens if my key is wrong or my quota runs out?

A 401 (invalid or missing subscription key) or a 403 (quota used up, or an API your plan does not include) ends the run cleanly with OAG's own words. Rate limits (429) are waited out and retried. A flight number, airport or date OAG refuses becomes a free row with the API's message, and the run moves on.

### Pricing

| Event | Price | Charged for |
| --- | --- | --- |
| `flight-record` | 0.01 USD | Each flight instance or effective schedule |
| `reference-record` | 0.005 USD | Each airport, airline or aircraft type |

### Keyword map

flight status API, flight tracker, flight schedules API, OAG API, OAG flight info, airline schedules, departures board, arrivals board, flight delay data, gate and terminal data, flight number lookup, aircraft registration lookup, tail number, codeshare flights, seat capacity, airport codes API, IATA ICAO codes, airline codes, aircraft type codes, aviation data API.

### Terms and data use

Use of the OAG Platform is governed by OAG's Terms of Service (developers.oag.com/terms-and-conditions). The licence covers your own personal or internal business purposes and commercial use within your subscription plan. It forbids reselling, sublicensing or redistributing raw OAG data, building a substitute database from it, storing it in an unsecured environment, and using it for safety-critical flight tracking or dispatch. Using OAG data with AI tools is subject to further conditions in clause 4.2. Run this actor with your own key, keep the results for your own use, and contact OAG before republishing or reselling the data. This actor is not affiliated with or endorsed by OAG.

# Actor input Schema

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

Flight status reads each flight number's instances (scheduled, estimated and actual times, gates, delays, diversions, seats). Flight search reads every flight matching a route, airport, airline, country or tail number. Flight schedules reads the effective schedule (date range and operating days) of IATA flight numbers. Airports, Airlines and Aircraft types read OAG master reference data.

## `flightNumbers` (type: `array`):

Flight status and Flight schedules. One flight per line: an airline code and a number, such as BA117, BAW117 or U2 8001. Schedules take 2 character IATA airline codes only.

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

Flight modes and Flight schedules. Local departure date in ISO 8601: 2026-10-20, a range such as 2026-10-20/2026-10-27 (at most 31 days), or for flight modes a time window such as 2026-10-20T06:00/2026-10-20T12:00. Leave empty for today.

## `arrivalDate` (type: `string`):

Flight status and Flight search. Local arrival date, range or time window in the same format, to search by arrival instead of (or as well as) departure.

## `departureAirports` (type: `array`):

Flight search only. IATA, ICAO or FAA airport codes flights depart from, such as LHR or EGLL. Give one airport for a departures board.

## `arrivalAirports` (type: `array`):

Flight search only. Airport codes flights arrive at. Combine with departure airports for a route, or use alone for an arrivals board.

## `carrierCodes` (type: `array`):

Flight search only. IATA or ICAO airline codes, such as BA, AAL or U2.

## `departureCountry` (type: `string`):

Flight search only. Two letter ISO 3166-1 code of the country flights depart from, such as US.

## `arrivalCountry` (type: `string`):

Flight search only. Two letter ISO 3166-1 code of the country flights arrive in, such as GB.

## `aircraftRegistration` (type: `string`):

Flight search only. Every flight flown by one aircraft, such as N425HB.

## `includeDiverted` (type: `boolean`):

Flight search with an arrival airport only. Also return flights diverted to that airport.

## `content` (type: `array`):

Flight status and Flight search. Extra data to include. OAG may charge extra for Seats, Actual seats and Extended schedules, depending on your plan.

## `flightTypes` (type: `array`):

Flight status and Flight search. Leave empty for all types.

## `serviceTypes` (type: `array`):

Flight status and Flight search. Leave empty for all services.

## `codeshare` (type: `array`):

Flight status and Flight search. Only operating flights, only marketing codeshares, or leave empty for both.

## `codeTypes` (type: `array`):

Which code standards your airport, airline and aircraft codes use. Leave empty to let the actor choose: IATA or ICAO by code length for flight numbers, IATA and ICAO elsewhere.

## `codes` (type: `array`):

Airports, Airlines and Aircraft types. Airport codes (LHR, EGLL), airline codes (BA, AAL) or aircraft type codes (320, A320). Leave empty to list everything that matches the other filters.

## `countryCodes` (type: `array`):

Airports only. Two letter ISO country codes; returns the airports in these countries.

## `cityCodes` (type: `array`):

Airports only. City codes such as LON or NYC; returns every airport serving the city.

## `names` (type: `array`):

Airlines: full or partial airline names. Aircraft types: full or partial manufacturer names, such as Airbus or Boeing.

## `aircraftModels` (type: `array`):

Aircraft types only. Full or partial model names, such as A320 or 787.

## `publishingCarriersOnly` (type: `boolean`):

Airlines only. Only airlines whose commercial schedules OAG publishes.

## `maxResults` (type: `integer`):

The most rows this run returns and charges for. Each page of up to 1000 rows is one request on your OAG plan.

## `requestsPerMinute` (type: `integer`):

Pacing. A rate limit answer is waited out and retried.

## `apiKey` (type: `string`):

Your own OAG subscription key (primary or secondary), from your profile on developers.oag.com. Stored as a secret and sent only in the Subscription-Key header to api.oag.com; it is never logged. You can instead set the DATA_API_KEY environment secret.

## Actor input object example

```json
{
  "mode": "flightStatus",
  "flightNumbers": [
    "BA117"
  ],
  "includeDiverted": false,
  "content": [
    "Status"
  ],
  "publishingCarriersOnly": false,
  "maxResults": 100,
  "requestsPerMinute": 60
}
```

# Actor output Schema

## `records` (type: `string`):

One row per flight, schedule, airport, airline or aircraft type.

# 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 = {
    "flightNumbers": [
        "BA117"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("nabeelbaghoor/flight-status-schedules-aviation-api").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 = { "flightNumbers": ["BA117"] }

# Run the Actor and wait for it to finish
run = client.actor("nabeelbaghoor/flight-status-schedules-aviation-api").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 '{
  "flightNumbers": [
    "BA117"
  ]
}' |
apify call nabeelbaghoor/flight-status-schedules-aviation-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nabeelbaghoor/flight-status-schedules-aviation-api"
        }
    }
}
```

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/wtG5eKlK1lgGhewUP/builds/u81fWcXZNvPwmX7qZ/openapi.json