# Suche im Flugverlauf

Archivierte ADS-B-Flüge nach Kennzeichen, ICAO24-Hex, Rufzeichen oder Route suchen – liefert flight_id-UUIDs für Detail- und Track-Abfragen.



Durchsuchen Sie archivierte Flüge nach Kennzeichen, **Rufzeichen** (das über [ADS-B](https://www.faa.gov/air_traffic/technology/adsb) ausgestrahlte Rufzeichen des Flugs, z. B. `BAW178`), Route oder Hex-Code und erhalten Sie eine Liste von Flügen mit `flight_id`-UUIDs. Mindestens ein Filter ist erforderlich. Dies ist der obligatorische erste Schritt in jedem Workflow mit historischen [ADS-B](https://www.faa.gov/air_traffic/technology/adsb)-Daten — ohne eine `flight_id` aus der Suche können die Endpoints für [Details](/docs/v31/historical-adsb-flight-detail#flight-detail) und [Track](/docs/v31/historical-adsb-flight-detail#flight-track) nicht aufgerufen werden.

Tarifstufen und Regeln für Pfadpräfixe: [Übersicht Historical ADS-B](/docs/v31/historical-adsb).

<DocRequirements>
  <DocRequirementAuth />

  <DocRequirement label="Tarif" href="/docs/rate-limits#historical-adsb-path-tiers">
    <strong>Pro</strong>, <strong>Ultra</strong> oder <strong>Mega</strong> — verwenden Sie das Pfadpräfix, das zum benötigten Zeitfenster passt (siehe [Vergleichstabelle in der Übersicht](/docs/v31/historical-adsb)).
  </DocRequirement>
</DocRequirements>

## Anfrage [#request]

<DocApiPath method="GET" path="/ultra/history/flights" />

| Parameter        | Typ     | Erforderlich            | Standard | Beschreibung                                                                    |
| ---------------- | ------- | ----------------------- | -------- | ------------------------------------------------------------------------------- |
| `start`          | string  | Nein                    | vor 24 h | Beginn des Abfragefensters — ISO 8601-Datum/Uhrzeit                             |
| `end`            | string  | Nein                    | jetzt    | Ende des Abfragefensters — ISO 8601-Datum/Uhrzeit                               |
| `icao24`         | string  | Ein Filter erforderlich | -        | ICAO24-Hex-Adresse (6 Zeichen)                                                  |
| `registration`   | string  | Ein Filter erforderlich | -        | Kennzeichen (z. B. `N12345`, `G-XWBA`). Wird serverseitig in `icao24` aufgelöst |
| `callsign`       | string  | Ein Filter erforderlich | -        | Exakte Übereinstimmung des Rufzeichens (z. B. `BAW117`)                         |
| `departure_icao` | string  | Ein Filter erforderlich | -        | ICAO-Code des Abflughafens (4 Zeichen)                                          |
| `arrival_icao`   | string  | Ein Filter erforderlich | -        | ICAO-Code des Zielflughafens (4 Zeichen)                                        |
| `limit`          | integer | Nein                    | `100`    | Maximale Anzahl zurückgegebener Flüge (max. **1.000** auf dem ULTRA-Pfad)       |

Werden sowohl `registration` als auch `icao24` angegeben, müssen sie sich auf dasselbe Luftfahrzeug beziehen. Auf dem ULTRA-Pfad darf das Abfragefenster **90 Tage** nicht überschreiten.

<DocDetails title="MEGA-Pfad (`/mega/history/...`)">
  <DocApiPath method="GET" path="/mega/history/flights" />

  | Parameter        | Typ     | Erforderlich            | Standard | Beschreibung                                                          |
  | ---------------- | ------- | ----------------------- | -------- | --------------------------------------------------------------------- |
  | `start`          | string  | Nein                    | vor 24 h | Fensterbeginn — ISO 8601 (max. **365 Tage** Spanne auf dem MEGA-Pfad) |
  | `end`            | string  | Nein                    | jetzt    | Fensterende — ISO 8601                                                |
  | `icao24`         | string  | Ein Filter erforderlich | -        | ICAO24-Hex (6 Zeichen)                                                |
  | `registration`   | string  | Ein Filter erforderlich | -        | Kennzeichen                                                           |
  | `callsign`       | string  | Ein Filter erforderlich | -        | Exaktes Rufzeichen                                                    |
  | `departure_icao` | string  | Ein Filter erforderlich | -        | ICAO des Abflughafens                                                 |
  | `arrival_icao`   | string  | Ein Filter erforderlich | -        | ICAO des Zielflughafens                                               |
  | `limit`          | integer | Nein                    | `200`    | Maximale Anzahl Flüge (max. **2.000** auf dem MEGA-Pfad)              |

  Erfordert den RapidAPI-Tarif **Ultra** oder **Mega**. Gleiche Parameter und gleiche Antwortstruktur wie ULTRA — nur die Obergrenzen für Fenster und Limit unterscheiden sich. Siehe die [Vergleichstabelle in der Übersicht](/docs/v31/historical-adsb).
</DocDetails>

## Antwort [#response]

```json
{
  "filters": {
    "icao24": null,
    "registration": null,
    "resolved_icao24": null,
    "callsign": null,
    "departure_icao": "EGLL",
    "arrival_icao": null
  },
  "count": 1,
  "flights": [
    {
      "flight_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "icao24": "40621d",
      "callsign": "BAW178",
      "flight_number": "BAW178",
      "tail_number": "G-XWBA",
      "aircraft_type_icao": "B77W",
      "aircraft_type_name": "Boeing 777-300ER",
      "airline_icao": "BAW",
      "airline_iata": "BA",
      "airline_name": "British Airways",
      "departure_airport_icao": "EGLL",
      "departure_airport_iata": "LHR",
      "departure_airport_name": "London Heathrow Airport",
      "arrival_airport_icao": "KJFK",
      "arrival_airport_iata": "JFK",
      "arrival_airport_name": "John F Kennedy International Airport",
      "flight_state": "ARCHIVED",
      "flight_start": "2026-05-12T19:42:05Z",
      "flight_end": "2026-05-13T03:11:10Z",
      "takeoff_time": "2026-05-12T19:45:00Z",
      "landing_time": "2026-05-13T03:08:00Z",
      "flight_duration_min": 443.0,
      "distance_nm": 2998.4,
      "confidence": 1.0,
      "route_source": "vrs_confirmed",
      "gps_spoofing_suspected": false,
      "diversion_suspected": false
    }
  ]
}
```

| Feld      | Typ     | Erforderlich | Beschreibung                                           |
| --------- | ------- | ------------ | ------------------------------------------------------ |
| `filters` | object  | **Ja**       | Echo der angewendeten Suchfilter (siehe unten)         |
| `count`   | integer | **Ja**       | Anzahl der Einträge in `flights`                       |
| `flights` | array   | **Ja**       | Zusammenfassungen der passenden Flüge (kann leer sein) |

### Angewendete Filter (`filters`) [#applied-filters-filters]

| Feld              | Typ            | Erforderlich | Null?  | Beschreibung                                           |
| ----------------- | -------------- | ------------ | ------ | ------------------------------------------------------ |
| `icao24`          | string \| null | **Ja**       | **Ja** | Abgefragter ICAO24-Hex, falls vorhanden                |
| `registration`    | string \| null | **Ja**       | **Ja** | Abgefragtes Kennzeichen, falls vorhanden               |
| `resolved_icao24` | string \| null | **Ja**       | **Ja** | Aus `registration` aufgelöster ICAO24, falls angegeben |
| `callsign`        | string \| null | **Ja**       | **Ja** | Abgefragtes Rufzeichen, falls vorhanden                |
| `departure_icao`  | string \| null | **Ja**       | **Ja** | Abgefragter Abflughafen, falls vorhanden               |
| `arrival_icao`    | string \| null | **Ja**       | **Ja** | Abgefragter Zielflughafen, falls vorhanden             |

<a id="flight-summary-flights" />

### Flugzusammenfassung (`flights[]`) [#flight-summary-flights]

| Feld                     | Typ             | Erforderlich | Null?  | Beschreibung                                                                                                                   |
| ------------------------ | --------------- | ------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `flight_id`              | string          | **Ja**       | Nie    | UUID für Detail- und Track-Abfragen                                                                                            |
| `icao24`                 | string \| null  | Nein         | **Ja** | Hex-Adresse des Luftfahrzeugs, sofern bekannt                                                                                  |
| `callsign`               | string \| null  | Nein         | **Ja** | ADS-B-Rufzeichen während des Flugs                                                                                             |
| `flight_number`          | string \| null  | Nein         | **Ja** | Normalisierte Flugnummer, sofern aufgelöst                                                                                     |
| `tail_number`            | string \| null  | Nein         | **Ja** | Kennzeichen, sofern bekannt                                                                                                    |
| `aircraft_type_icao`     | string \| null  | Nein         | **Ja** | ICAO-Typcode (z. B. `B77W`)                                                                                                    |
| `aircraft_type_name`     | string \| null  | Nein         | **Ja** | Lesbare Bezeichnung des Luftfahrzeugtyps                                                                                       |
| `airline_icao`           | string \| null  | Nein         | **Ja** | ICAO-Code der Fluggesellschaft                                                                                                 |
| `airline_iata`           | string \| null  | Nein         | **Ja** | IATA-Code der Fluggesellschaft                                                                                                 |
| `airline_name`           | string \| null  | Nein         | **Ja** | Anzeigename der Fluggesellschaft                                                                                               |
| `departure_airport_icao` | string \| null  | Nein         | **Ja** | ICAO des Abflughafens, sofern aufgelöst                                                                                        |
| `departure_airport_iata` | string \| null  | Nein         | **Ja** | IATA des Abflughafens                                                                                                          |
| `departure_airport_name` | string \| null  | Nein         | **Ja** | Name des Abflughafens                                                                                                          |
| `arrival_airport_icao`   | string \| null  | Nein         | **Ja** | ICAO des Zielflughafens, sofern aufgelöst                                                                                      |
| `arrival_airport_iata`   | string \| null  | Nein         | **Ja** | IATA des Zielflughafens                                                                                                        |
| `arrival_airport_name`   | string \| null  | Nein         | **Ja** | Name des Zielflughafens                                                                                                        |
| `flight_state`           | string \| null  | Nein         | **Ja** | Archivstatus (z. B. `ARCHIVED`)                                                                                                |
| `flight_start`           | string          | **Ja**       | Nie    | Erste archivierte Beobachtung (ISO 8601)                                                                                       |
| `flight_end`             | string          | **Ja**       | Nie    | Letzte archivierte Beobachtung (ISO 8601)                                                                                      |
| `takeoff_time`           | string \| null  | Nein         | **Ja** | Geschätzter oder erkannter Start (ISO 8601)                                                                                    |
| `landing_time`           | string \| null  | Nein         | **Ja** | Geschätzte oder erkannte Landung (ISO 8601)                                                                                    |
| `flight_duration_min`    | number \| null  | Nein         | **Ja** | Gate-to-Gate-Dauer in Minuten                                                                                                  |
| `distance_nm`            | number \| null  | Nein         | **Ja** | Großkreisentfernung in nautischen Meilen                                                                                       |
| `confidence`             | number \| null  | Nein         | **Ja** | Konfidenzwert der Route (0–1)                                                                                                  |
| `route_source`           | string \| null  | Nein         | **Ja** | Opaker Enum-Wert, der beschreibt, wie die Route aufgelöst wurde — als Anzeigewert behandeln, nicht als Schlüssel für Abgleiche |
| `gps_spoofing_suspected` | boolean \| null | Nein         | **Ja** | Ob für diesen Flug GPS-Spoofing markiert wurde                                                                                 |
| `diversion_suspected`    | boolean \| null | Nein         | **Ja** | Ob für diesen Flug eine Umleitung markiert wurde                                                                               |

## Client-Typen [#client-types]

<DocClientTypes id="v31/historical-adsb/history-types" />

## Integration [#integration]

Der typische Workflow ist **Suche → Details** (Metadaten) oder **Suche → Track** (Wiedergabe auf der Karte). Suchen Sie mit mindestens einem Filter, übernehmen Sie eine `flight_id` aus den Ergebnissen und rufen Sie dann [Details](/docs/v31/historical-adsb-flight-detail#flight-detail) oder [Track](/docs/v31/historical-adsb-flight-detail#flight-track) auf.

Das folgende Beispiel sucht nach Abflughafen, ruft die vollständigen Metadaten für den ersten Treffer ab und verwendet Verbindungs- und Lese-Timeouts, damit Batch-Jobs nicht unbegrenzt hängen bleiben. Behandeln Sie bei Tarifen ohne Zugriff auf historische [ADS-B](https://www.faa.gov/air_traffic/technology/adsb)-Daten die Gateway-Antworten `401`/`403`, bevor Sie JSON parsen — siehe [Übersicht → Fehlerantworten](/docs/v31/historical-adsb#error-responses).

<DocExample id="v31/historical-adsb/history-fetch" />

### Hinweise zur Implementierung [#implementation-notes]

**Wählen Sie das richtige Pfadpräfix.** Verwenden Sie `/ultra/history/...` ab Pro, wenn ein Fenster von 90 Tagen ausreicht. Verwenden Sie `/mega/history/...` mit Ultra/Mega, wenn Sie bis zu 365 Tage oder höhere Limits pro Anfrage benötigen.

**Verketten Sie über `flight_id`.** Raten Sie niemals Zeitfenster für die Track-Wiedergabe — suchen Sie zuerst und rufen Sie dann `/history/flight/{flight_id}/track` für einen automatisch begrenzten Pfad auf.

**Paginieren Sie große Fenster.** Wenn `count` dem angeforderten `limit` entspricht, verkleinern Sie das Fenster `start`/`end` oder erhöhen Sie `limit` (innerhalb der Obergrenzen der Stufe) und führen Sie die Ergebnisse clientseitig zusammen.

**Kennzeichen vs. Hex.** Bevorzugen Sie `registration`, wenn Ihre Benutzer Kennzeichen kennen; verwenden Sie `icao24`, wenn Sie rohe [ADS-B](https://www.faa.gov/air_traffic/technology/adsb)-Feeds verarbeiten.

## Fehlerantworten [#error-responses]

Tarifbedingte `401`/`403`: [Übersicht Historical ADS-B](/docs/v31/historical-adsb#error-responses). Endpoint-spezifisch:

### 422 — kein Suchfilter [#422--no-search-filter]

Mindestens einer der Parameter `icao24`, `registration`, `callsign`, `departure_icao` oder `arrival_icao` ist erforderlich:

```json
{
  "detail": [
    {
      "type": "value_error",
      "loc": ["query"],
      "msg": "At least one filter (icao24, registration, callsign, departure_icao, arrival_icao) is required"
    }
  ]
}
```

### 422 — Fenster zu groß [#422--window-too-wide]

Wird zurückgegeben, wenn die Spanne `start`/`end` das Maximum des Pfads überschreitet — **90 Tage** auf `/ultra/history/...` oder **365 Tage** auf `/mega/history/...`:

```json
{
  "detail": "Query window exceeds maximum of 90 days for your plan on /ultra/history/..."
}
```

### 422 — Kennzeichen und ICAO24 stimmen nicht überein [#422--registration-and-icao24-mismatch]

Wenn beide Kennungen angegeben werden, sich aber auf unterschiedliche Luftfahrzeuge beziehen:

```json
{
  "detail": "registration and icao24 refer to different aircraft"
}
```

<APIPage document="&#x22;https://api.skylinkapi.com/v3.1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/ultra/history/flights&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/mega/history/flights&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />