A flight delay API that calls you.
Most delay APIs answer a question: is this flight late? FlightByte asks it for you, on a schedule that tightens as departure nears, and sends a signed webhook when the delay grows or shrinks by more than you care about. One flight, one date, one subscription.
What it is, and what it is not
“Flight delay API” means three different products. FlightByte is one of them.
What FlightByte does
- Watches a flight you name, by carrier, number and date, up to seven days ahead.
- Tells you when its delay grows or shrinks, with departure and arrival delay in minutes.
- Tells you about the cancellation, the diversion and the new estimate in the same stream.
- Pushes each one as a signed, retried, logged webhook. You never poll.
What it does not
- Airport-wide delays. No delay index or statistics for an airport as a whole.
- History. No on-time performance or past delays beyond a few days back.
- Prediction. No model guessing at delays the airline has not published.
- For those, see AeroDataBox or FlightAware AeroAPI.
How a delay reaches you
Three steps, and only the first one is code you write.
Subscribe, with a threshold
Name the flight, the date and the events your messages depend on. delayThresholdMinutes is the first filter: movements smaller than it are never sent. metadata comes back in every delivery, so a webhook maps straight to your booking.
POST https://api.flightbyte.dev/v1/subscriptions
x-api-key: $FLIGHTBYTE_KEY
{
"carrier": "TK",
"flightNumber": "1848",
"date": "2026-09-12",
"origin": "ATH",
"webhookUrl": "https://yourapp.com/hooks/flights",
"delayThresholdMinutes": 15,
"events": [
"delay.increased", "delay.decreased",
"flight.cancelled", "flight.reinstated", "flight.diverted",
"departure.scheduled.changed"
],
"metadata": { "bookingId": "BK-1042" }
}FlightByte watches
The flight is polled on its own schedule: every few hours a week out, every three minutes at the gate, then a window for the baggage belt, then the subscription completes itself. Every answer is compared with the last one; only the differences you asked for, and only those past your threshold, go out.
A delivery arrives
A POST signed with HMAC-SHA256 over a timestamp and the raw body. changes says what moved and by how much; the snapshot says where the delay stands now.
{
"type": "flight.updated",
"flightKey": "TK1848:2026-09-12@ATH-IST",
"changes": [
{ "type": "delay.increased", "deltaMinutes": 25, "message": "…" },
{
"type": "departure.estimated.changed",
"path": "departure.times.estimatedGate",
"from": "2026-09-12T08:10:00Z",
"to": "2026-09-12T08:35:00Z",
"deltaMinutes": 25,
"message": "Departure estimated gate time changed from 2026-09-12T08:10:00Z to 2026-09-12T08:35:00Z"
}
],
"flight": {
"departure": { "delayMinutes": 35, "bestTimeUtc": "2026-09-12T08:35:00Z", "…": "…" },
"arrival": { "delayMinutes": 30, "…": "…" },
"status": { "phase": "boarding", "delayed": true, "…": "…" }
},
"metadata": { "bookingId": "BK-1042" }
}Trimmed. The full format, headers and signature check are in Webhooks.
The events a delay watch asks for
Seven of the 23 change types. Gates, terminals and baggage are there too when you want them.
| Event | When it fires |
|---|---|
delay.increased | The gate delay grew by at least your threshold. |
delay.decreased | It shrank by at least your threshold, including back to on time. |
departure.estimated.changed | The airline moved its departure estimate, with deltaMinutes. |
arrival.estimated.changed | The same on arrival: the number a driver or a hotel acts on. |
departure.scheduled.changed | The timetable itself moved, days out. Not a delay, but it changes what on time means. |
flight.cancelled | Cancelled; flight.reinstated if it comes back. |
flight.diverted | Landing somewhere other than planned. |
What “delayed” means in the data
A delay is a difference between two times, and FlightByte does the subtraction: estimated or actual gate time minus scheduled gate time, on each side of the flight.
| Field | Meaning |
|---|---|
departure.delayMinutes | Minutes behind the scheduled gate departure. Negative when early, absent when no estimate exists yet. |
arrival.delayMinutes | The same on arrival, which is the number a driver or a hotel wants. |
status.delayed | True when either side is late by the airline's own definition. |
bestTimeUtc | The best time known right now on that side: actual, else estimated, else scheduled. |
A delayed flight is still scheduled, or en_route, or landed: the phase says where the aircraft is, the delay says how far behind the timetable it is. The guide Building a flight delay notification system turns this into rules: when to tell whom, how to stay quiet through drift, and what to say when it recovers.
Who it is for
Anyone with a booking that depends on a flight being on time.
Polling a delay endpoint, or being told
A delay endpoint polled every five minutes for the last six hours is 72 requests a flight, and still learns of a change up to five minutes late. With a subscription the polling is FlightByte’s, and the price is per watched flight, however many deliveries it takes.
Every event type, 4,000 lookups, extra flights at $0.08.
Every event type, 20,000 lookups, extra flights at $0.05.
Every event type, 80,000 lookups, extra flights at $0.03.
Every event type, 200,000 lookups, extra flights at $0.02.
The arithmetic in full is in Why polling a flight API costs more than you think; the plans are on the pricing page.
Questions about delay alerts
Does FlightByte have historical delay data or airport delay statistics?
Does it predict delays?
How quickly does a delay reach me?
Can I ignore small delays?
delayThresholdMinutes on the subscription, from 1 to 240; the default is 1. Delay movements smaller than that are not delivered, so a ten-minute drift never reaches a desk that only acts on thirty.Departure delay or arrival delay?
departure.delayMinutes and arrival.delayMinutes, gate time minus scheduled gate time, negative when early and absent when there is no estimate yet. The delay.increased and delay.decreased events follow the gate delay; read the side your audience cares about from the snapshot.Hear about the next delay first.
A key, one subscription, and a receiver. The quickstart has it in Node and Python.
A free key in a minute, no card. On a paid plan? Request a key