Looking flights up, choosing a leg when a number flies twice, the timeline, and how caching works.

Looking a flight up

GET /v1/flights/{carrier}/{flightNumber}/{date}

Part	Meaning
`carrier`	Airline code, two or three characters: `TK`, `PC`, `3U`.
`flightNumber`	One to four digits, an optional letter suffix; leading zeros are ignored, so `0012` and `12` are the same flight.
`date`	`YYYY-MM-DD`, the local departure date at the origin. A flight that leaves Istanbul at 23:50 and lands the next morning is on the day it left.

The same lookup is available as a query: GET /v1/flights/search?carrier=TK&flightNumber=1848&date=2026-09-12.

Optional query parameters on both:

Parameter	Use
`origin`	Pick a leg by departure airport. Accepts the IATA code (`IST`) or the code the data upstream uses (`ISL`); both resolve to the same leg.
`destination`	Narrow further when several legs leave the same airport.
`flightId`	Exact pick using `alternates[].providerFlightId` from a previous answer.
`refresh`	`true` skips the cache and asks upstream now. Counts as a normal request.

The response is the flight snapshot plus one field, cached, that says whether it came from cache.

Leg selection

Flight numbers are not unique within a day. TK1 is SAW → AMS in the morning and IST → JFK in the afternoon. FlightByte never guesses which one you mean:

Lookups without a selector return the upstream's default leg and list every leg under alternates, with selected: true on the one described.
Lookups with a selector that matches nothing answer 404 and name the legs that exist.
Subscriptions for an ambiguous number without a selector are refused with 400 and the legs, because watching the wrong aircraft is worse than an error.

404 when the selector matches nothing

{
  "statusCode": 404,
  "error": "NotFoundException",
  "message": "TK1 on 2026-09-12 has no leg matching origin=LHR. Available: SAW-AMS, ISL-JFK."
}

Use origin: a passenger always knows where they are leaving from. The resolved leg gets a canonical key, TK1:2026-09-12@IST-JFK, which is what appears in webhooks and subscriptions.

The snapshot

One shape for every flight, whichever upstream it came from.

Field	What it holds
`flightKey`	Canonical key: `TK1848:2026-09-12` or, once a leg is resolved, `TK1848:2026-09-12@ATH-IST`.
`carrier`, `operatedBy`, `codeshares`	Marketing airline, operating airline when different, and every codeshare number.
`departure`, `arrival`	Airport (with country, emoji and flag URLs), terminal, gate, `baggage` on arrival, `times`, `bestTimeUtc`, `delayMinutes`.
`times`	`scheduledGate`, `estimatedGate`, `actualGate`, `scheduledRunway`, `estimatedRunway`, `actualRunway`, each with `utc`, `local` and `timezone`. Missing ones are absent, not guessed.
`bestTimeUtc`	The best time known right now: actual, else estimated, else scheduled. Use this when you need one number.
`status`	`code` (upstream letter), `label`, `phase`, and the booleans `delayed`, `cancelled`, `diverted`, plus gate delays in minutes.
`diverted`	The airport the flight went to instead, when it did.
`equipment`	Aircraft type and tail number.
`duration`	Scheduled, estimated and actual minutes.
`timeline`	The airline's own history of changes for this leg, newest first.
`alternates`	Every leg this number operates that day.
`fetchedAt`	When this snapshot was taken upstream.

Phases

status.phase is the field to branch on; status.code and label carry the upstream's wording.

Phase	Meaning
`scheduled`	Not yet departed.
`boarding`	Gate activity reported.
`departed`	Left the gate, not yet airborne.
`en_route`	Airborne.
`landed`	On the ground, not yet at the gate.
`arrived`	At the gate; watch continues briefly for the baggage carousel.
`cancelled`, `diverted`, `redirected`	Terminal states with the obvious meaning.
`unknown`	Upstream said nothing usable.

Timeline

GET /v1/flights/{carrier}/{flightNumber}/{date}/timeline

Returns { "flightKey", "count", "data": [...] } where each entry has occurredAt, title, source and a list of events in the airline's words, newest first. It is the same data as snapshot.timeline, exposed on its own for pages that only need the history.

Caching

Lookups are served from cache while fresh; the cached flag says which. Concurrent requests for the same flight collapse into one upstream call.

Flight state	Cache lifetime
Departs in more than 24 hours	30 minutes
Departs in 3 to 24 hours	5 minutes
Within 3 hours of departure or in the air	60 seconds
Completed	60 minutes
More than 48 hours in the past	7 days
Not found	2 minutes

If you need a guaranteed fresh answer, pass refresh=true. For anything you want to be told about rather than ask for, subscribe.

Coverage

Live records exist for flights from a few days before today to a couple of days ahead. A lookup outside that window answers 404. A subscription can still be created up to seven days ahead: it waits as pending and activates by itself when the flight appears.

Flights