The Flight Status Lifecycle: Scheduled, Departed, In Air, Arrived

A flight moves through a handful of states, and each one tells you a different thing to do — and a different time field to trust. Here is how to read the status through the whole journey, and how to drive a workflow off the transitions instead of polling a snapshot.

August 3, 2026 · · 4 min read

Every flight your integration touches is somewhere on a short journey: it is planned, it leaves, it flies, it lands. The status field names where it is on that journey — and the single most useful habit in flight integration is to let the status decide what your system does next. A driver is dispatched on one status, released on another; an alert means one thing before departure and something else in the air. This guide walks the whole lifecycle: what each status means, which time field to trust at each stage, and how to act on the transitions rather than re-reading a snapshot.

The states

• Scheduled — the flight is planned but hasn't left. You have scheduled times; estimated usually mirrors them until the day firms up.
• Departed / In Air — the aircraft has left the gate and is flying. Now the estimated arrival is the number that matters, refining as the flight progresses.
• Arrived — it has landed. The actual times are recorded and are now the truth; the journey is complete.
• Cancelled — it will not operate. A terminal state that needs its own response (notify, rebook).
• Diverted — it went somewhere other than planned. Terminal for the original destination; the flight surfaces the airport it actually reached.

Which time to trust at each stage

The status tells you which of the three times (scheduled, estimated, actual) is the live answer:

• Scheduled: read gateDepartureTimes.scheduled for planning; treat it as the plan, not a promise.
• Departed / In Air: the departure actual is set, and the number that matters downstream is gateArrivalTimes.estimated — the live arrival prediction.
• Arrived: gateArrivalTimes.actual (and landingTimes.actual) are set — use them for reporting and to close out the job.

A single fallback captures the rule at any stage: prefer the most real value present.

# the arrival time to act on, whatever the stage
eta = gateArrivalTimes.actual or gateArrivalTimes.estimated or gateArrivalTimes.scheduled
landed = gateArrivalTimes.actual is not None

Reading the status in the response

Each flight carries a status block alongside the times. status is the human-readable state; timesAvailable tells you whether times are populated yet; scheduleConfidence tells you how firm those times are (from a plan vs a confirmed record vs an observed actual).

{
  "status": "In Air",
  "timesAvailable": true,
  "scheduleConfidence": "actual"
}

Use status to branch your logic, and scheduleConfidence to decide how much to lean on the times — a high-confidence estimate is worth dispatching on; a provisional one is worth a wider buffer.

Act on transitions, not snapshots

The mistake that makes flight integrations brittle is polling the status on a timer and re-deriving "did anything change?" every time. The states above are only useful as transitions: Scheduled → Departed is when you stage the pickup; In Air → Arrived is when you release the driver to the curb; a jump to Cancelled or Diverted is when you run the disruption playbook. Instead of polling, create a monitor and let the transition come to you:

curl -X POST "https://api.flightnerve.com/monitor/YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "flight": "EK72", "date": "20260803" }'

You then receive the departure, delay, gate, landing, cancellation and diversion events as they happen — each already telling you what changed — so your workflow reacts to the transition itself rather than discovering it late on a poll.

A status-to-action map

• Scheduled → hold; watch the estimated departure.
• Departed / In Air → stage the downstream action against the estimated arrival.
• Arrived → complete the job on the actual arrival.
• Cancelled → notify + rebook/refund.
• Diverted → redispatch to the airport it actually reached.

Frequently asked questions

What are the possible status values?

The common ones are Scheduled, In Air, and Arrived, plus the terminal branches Cancelled and Diverted. Branch your logic on this field.

The status is "In Air" but there's no arrival time — what do I use?

Fall back to gateArrivalTimes.estimated, and for a live countdown read etaMinutes from the /track endpoint. If both are absent, use the scheduled arrival with a buffer until the estimate appears.

What does scheduleConfidence tell me?

How firm the times are — from an observed actual, a confirmed record, a published schedule, or a provisional projection. Dispatch confidently on higher confidence; widen your buffer on lower.

How do I know the exact moment a flight lands?

Watch for gateArrivalTimes.actual (or landingTimes.actual) to become non-null, or subscribe to a monitor and receive the landing event as it happens.

Should I poll the status to catch changes?

No — create a monitor and react to the transition. Polling misses short-lived changes and costs more calls.

Read the status to know the stage, trust the matching time field, and act on the transitions. Do that and your dispatches, alerts and reports stay in step with where the flight actually is — not where a stale snapshot said it was.