> ## Documentation Index > Fetch the complete documentation index at: https://docs.skyvexsoftware.com/llms.txt > Use this file to discover all available pages before exploring further. # Additional Fields > Complete reference for the Additional Fields matrix VAs use to choose which optional fields ride along on position updates and the completion PIREP sent to their own ACARS backend, with the exact wire key, type and unit of every field. The **Flight Tracking** plugin sends a periodic position update on the interval set by the airline's **Tracking Interval** (15 / 30 / 60 seconds) and, at the end of a flight, a single completion PIREP. When a VA has a backend URL configured for its own ACARS (phpVMS, vmsACARS, custom), every report sent to that backend carries a fixed set of core fields plus whichever extras the airline has opted into. The **Additional Fields** setting is one matrix that controls all of that. Every optional field is a row; the 15 flight phases are columns, with a final **Submission** column. Tick a phase cell to append that field to position updates **while the flight is in that phase**; tick **Submission** to include it in the completion PIREP. This single matrix replaces the two older lists (the streamed "Position Report Fields" and the completion "PIREP Fields") — an airline configured under the old model is migrated automatically, preserving its previous behaviour (everything it streamed keeps streaming in every phase, everything it submitted keeps being submitted). This page lists every field, the exact key it uses on the wire, its type and unit, and what it represents, so VA admins know what to enable and what their own backend will receive. It is kept in sync with the client code — when a new variable is added, it is added here. ## Where to configure In your Skyvex admin: **Airlines → \ → Plugins → Flight Tracking → Additional Fields**. Tick any combination of phase cells and Submission per field. The selection is stored on the airline and applies to every pilot the next time they (re)start a flight — the Stratos client pulls the config at the start of each flight. Lower the **Tracking Interval** and tick more phase cells only if your VA backend actually consumes them. Each extra field is more bytes per pilot per tick — fine in isolation, noticeable at scale across hundreds of pilots flying simultaneously. Restricting a field to the phases that matter (for example winds only during `CLIMB` / `CRUISE` / `DESCENT`) keeps every other tick lean. ## What every report always carries Two sets of fields are sent unconditionally, regardless of what you tick. ### Position update — the always-on keys Every position update POSTed to your backend's `/flights/update` opens with these twelve keys, in this order, before any optional fields are appended: | Key | Description | Type / Unit | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `uuid` | The VA-side tracking id for this flight. Always the first key. Not sim-sourced. | string | | `bid_id` | The VA booking id the flight was started from. | number | | `phase` | Current flight phase, **UPPERCASE** (`BOARDING` … `DEBOARDING`). `TAXI_IN` and `ARRIVED` both report as `TAXI_TO_GATE`; an undetected phase is `UNKNOWN`. Reports `PAUSED` while the sim is paused. See [The phase fields](#the-phase-fields). | string | | `latitude` | Aircraft latitude in WGS-84. | number, ° | | `longitude` | Aircraft longitude in WGS-84. | number, ° | | `heading` | True heading. | number, ° | | `altitude` | Altitude MSL. | number, ft | | `ground_speed` | Ground speed. | number, kts | | `distance_remaining` | Great-circle distance from the current position to the destination airport. `0` only when the destination is unknown (free flight, or its coordinates haven't synced). | number, nm | | `time_remaining` | `distance_remaining ÷ ground_speed`, in hours; `0` when stationary or when `distance_remaining` is `0`. | number, hr | | `route` | The filed route string for the booking. | string | | `network` | Always the literal string `"offline"`. | string | The opt-in `miles_to_go` field carries the same value as `distance_remaining`, which is already always present — so there is no need to enable `miles_to_go` separately. ### Completion PIREP — the always-on keys The completion POST to `/flights/complete` always includes these thirteen keys, before any **Submission**-ticked fields are merged on top: | Key | Description | Type / Unit | | ------------------- | ---------------------------------------------------------------------------------------------------------- | ----------- | | `tracking_id` | Identifies the flight being completed. | string | | `bid_id` | The VA booking id. | number | | `status` | Completion status (`completed`, `diverted`, and so on). | string | | `flight_time` | Total flight duration. | number, hr | | `landing_rate` | Touchdown vertical rate, from the landing analyser. | number, fpm | | `fuel_used` | Fuel burned over the flight. | number, lbs | | `block_fuel` | Fuel on board at block-off. **Omitted from the JSON entirely** if it was never captured (not sent as `0`). | number, lbs | | `zfw` | Zero-fuel weight at start. **Omitted entirely** if never captured. | number, lbs | | `simulator_version` | Simulator name and version. | string | | `comments` | Pilot and auto-generated comments. | string | | `history` | Thinned (\~15 s) position track, as a JSON array of `{time, latitude, longitude, alt, gs}`. | JSON array | | `flight_log` | Recorded flight events, as a JSON array of `{timestamp, event}`. | JSON array | | `landing_report` | The landing-analyser report object. | object | `landing_rate`, `fuel_used` and `simulator_version` are always included here with their authoritative completion values, so **Submission is disabled for them** in the matrix — ticking it would only override the authoritative value with the live one, so there is nothing to add. ## How optional fields are delivered Every optional field is one of two kinds. This determines what your backend receives and when: * **Live** — read from the simulator on every tick and sent at its current value. If the sim can't supply it, the raw default is sent: `0` for numbers, `false` for booleans, `""` for strings. Live fields are never blank. * **Milestone** — captured once when the flight passes a milestone (block-off, takeoff, touchdown, block-on) and stored in the PIREP snapshot. A milestone field appended to a position update **before** its capture milestone is sent as `null`; the same applies to a Submission-ticked milestone field whose milestone never fired. Each table below marks the kind. Per-simulator caveats are folded into the description, because the admin matrix's "all sims" badge does not capture every gap. ## Optional live fields Grouped as they appear in the admin matrix. The **Key** column is the exact key your VA backend sees in the JSON payload. ### Position & Navigation | Key | Description | Type / Unit | | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `vertical_speed` | Climb / descent rate, positive = climb. X-Plane uses an undamped value (`local_vy`), not the cockpit VSI. | number, fpm | | `indicated_airspeed` | Indicated airspeed (rounded). | number, kts | | `true_airspeed` | True airspeed (rounded). | number, kts | | `altitude_agl` | Height above ground level (aircraft reference point). | number, ft | | `altitude_agl_gear` | AGL measured to the main gear (minus CG). Only MSFS gives a distinct minus-CG value; **FSX/P3D and X-Plane fall back to `altitude_agl`**. | number, ft | | `miles_to_go` | Great-circle distance to the destination airport — the same value as the always-on `distance_remaining`. `0` when the destination is unknown. | number, nm | | `cruise_altitude` | **Not a filed cruise level.** The current MSL altitude rounded to the nearest 1000 ft. | number, ft | ### Orientation | Key | Description | Type / Unit | | ------- | ----------------------------------------------------------------- | ----------- | | `pitch` | Pitch attitude, positive = nose up (sign normalised across sims). | number, ° | | `bank` | Bank angle (positive = right wing down). | number, ° | ### Flight Controls | Key | Description | Type / Unit | | ---------------------- | ------------------------------------------------------------------------------------------------ | ----------- | | `gear_control` | Gear handle down (`true` = down). Debounced \~3 s to avoid toggling during gear animation. | boolean | | `flaps_control` | Flap **handle** position, 0–100 %. | number, % | | `flaps_left_position` | **Not a real per-surface reading** — aliased to `flaps_control`. | number, % | | `flaps_right_position` | **Not a real per-surface reading** — aliased to `flaps_control`. | number, % | | `on_ground` | On-ground flag. MSFS also applies a low-and-slow heuristic; X-Plane reads the sim flag directly. | boolean | ### Engine Data `engines_count` reports how many engines the current aircraft has — use it to ignore `engine3_*` / `engine4_*` on twins. Per-engine fields exist for all four slots; on X-Plane the unused slots are masked to `0` / `false`. For each engine there are two "running" signals: `engineN_firing` is the **raw combustion flag** (it can flicker on some MSFS 2024 aircraft), while `engineN_on` is a **debounced, composite running flag** that is more stable. Prefer `engineN_on` for "is the engine running". | Key | Description | Type / Unit | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ----------- | | `engines_count` | Number of engines on the aircraft. | number | | `engine1_firing` … `engine4_firing` | Raw combustion flag for engine 1–4 (fuel burning). Can flicker on some MSFS 2024 aircraft. | boolean | | `engine1_on` … `engine4_on` | Debounced "engine running" flag for engine 1–4 (combustion plus an N1/RPM fallback, with a commit delay). The stable signal. | boolean | | `engine1_n1` … `engine4_n1` | Turbine N1 (fan / low-pressure spool). On MSFS 2024 this is the most reliable engine-running indicator. | number, % | | `engine1_n2` … `engine4_n2` | Turbine N2 (high-pressure spool). Can read wrong on some MSFS 2024 aircraft. | number, % | | `engine1_pct_rpm` … `engine4_pct_rpm` | RPM as a percentage of redline (works for pistons too). **MSFS / FSX / P3D only — X-Plane always reports `0`.** | number, % | ### Fuel | Key | Description | Type / Unit | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `fuel_quantity` | Total fuel **weight** on board. In **pounds** (easy to mistake for kg). | number, lbs | | `fuel_used` | Fuel burned since the configured start phase (starting fuel − current fuel weight). `0` until the start-fuel milestone is captured (pushback or takeoff, per your config), then tracks live. | number, lbs | ### Weather | Key | Description | Type / Unit | | -------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------ | | `wind_direction` | Wind direction (true, from). | number, ° | | `wind_speed` | Wind speed. | number, kts | | `pressure_qnh` | Ambient / sea-level pressure in **inHg** (\~29.92), **not hPa** despite the name. Both sims emit inches of mercury. | number, inHg | | `altimeter_settings` | Altimeter (Kohlsman) setting in inHg. On X-Plane this duplicates `pressure_qnh` (no separate Kohlsman read). | number, inHg | ### Simulation Time The simulator's in-world clock, for logging what time it is *in the sim* rather than in the real world. | Key | Description | Type / Unit | | --------------------- | ----------------------------------------------------------------------- | ----------- | | `clock_hour` | Local clock hour (0–23). | number | | `clock_min` | Local clock minute (0–59). | number | | `clock_sec` | Local clock second (0–59). | number | | `zulu_hour` | Zulu (UTC) hour (0–23). | number | | `zulu_min` | Zulu minute (0–59). | number | | `zulu_day_of_month` | Zulu day of month (1–31). On X-Plane this is aliased to the local date. | number | | `zulu_month_of_year` | Zulu month (1–12). On X-Plane aliased to the local month. | number | | `zulu_year` | Year (4-digit). The real-world system year, not a sim-set year. | number | | `local_day_of_month` | Local day of month (1–31). | number | | `local_month_of_year` | Local month (1–12). | number | | `local_year` | Year (4-digit). The real-world system year. | number | ### Aircraft Information | Key | Description | Type / Unit | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `aircraft_type` | Sim-reported model name (with livery appended when known). | string | | `aircraft_icao` | ICAO type designator (for example `B738`, `A320`). Also captured as a milestone at takeoff (the live value is the one sent on ticks). | string | | `aircraft_livery` | Livery / title. **MSFS 2024 and X-Plane only** — MSFS 2020 / FSX / P3D leave it empty. Also captured as a milestone at takeoff. | string | | `aircraft_empty_weight` | Empty weight of the aircraft, in pounds. | number, lbs | | `zero_weight_plus_payload` | Zero-fuel weight (airframe plus payload, no fuel), in pounds. | number, lbs | ### Simulator State | Key | Description | Type / Unit | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `simulator_version` | Detected simulator and version (for example `Microsoft Flight Simulator 2024`, `X-Plane 12`). | string | | `pause_flag` | Simulator is paused. When `true`, the always-on top-level `phase` reports `PAUSED`. On X-Plane, 0× time compression folds into this flag. | boolean | | `slew_mode` | Aircraft is in slew mode. **MSFS / FSX / P3D only — X-Plane always `false`.** | boolean | | `simulation_rate` | Sim time multiplier (`1` = real time, `4` = 4×). Dimensionless. | number | | `is_in_menu` | Sim is showing a menu / not in active flight. **MSFS / P3D only — FSX and X-Plane always `false`.** | boolean | | `is_xplane` | `true` only when the connected simulator is X-Plane. A reliable sim discriminator. | boolean | ### Warnings | Key | Description | Type / Unit | | ------------------- | ---------------------------------------- | ----------- | | `stall_warning` | Stall warning is active. | boolean | | `overspeed_warning` | Overspeed warning is active. | boolean | | `crashed` | Sim has flagged the aircraft as crashed. | boolean | ### Landing Analysis These live fields are easy to misread — most are **not** the held touchdown values their names suggest. For authoritative touchdown figures, use the milestone `landing_*` fields below or the completion `landing_report`. | Key | Description | Type / Unit | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | | `g_force_touchdown` | **Live, instantaneous** normal G load (\~1.0 in level flight), not a held touchdown peak. | number, G | | `landing_rate` | In the air this is the live vertical speed (MSFS / FSX / P3D; X-Plane reports `0`). **After touchdown it holds the landing analyser's canonical touchdown rate** on every sim — the same value the completion report uses. | number, fpm | | `touchdown_normal_velocity` | Touchdown vertical velocity. `0` until touchdown, then **held on every sim** — MSFS uses its native latched value; X-Plane / FSX / P3D carry the landing analyser's canonical touchdown rate (so it agrees with `landing_rate`). | number, fpm | | `touchdown_latitude` | Latitude at touchdown. `0` until touchdown, then **held on every sim** for the rest of the flight. | number, ° | | `touchdown_longitude` | Longitude at touchdown. `0` until touchdown, then **held on every sim** for the rest of the flight. | number, ° | | `landing_distance` | Rollout distance from touchdown to where the aircraft slows or turns off, from the landing analyser. `0` until the rollout is measured (around `TAXI_IN`), then held for the rest of the flight. | number, ft | ### Navigation | Key | Description | Type / Unit | | ------------- | ---------------------------------------------------------------------------- | ----------- | | `transponder` | Transponder squawk code, as a **string**. | string | | `com1_freq` | COM1 active frequency, decimal MHz string to 3 dp (for example `"118.100"`). | string, MHz | | `com2_freq` | COM2 active frequency, MHz string to 3 dp. | string, MHz | | `nav1_freq` | NAV1 active frequency, MHz string to 2 dp (for example `"110.60"`). | string, MHz | | `nav2_freq` | NAV2 active frequency, MHz string to 2 dp. | string, MHz | ## Optional milestone fields Captured once at a flight milestone and held for the rest of the flight. Sent as `null` until their milestone passes. Group order matches the admin matrix. ### Departure Captured at block-off (first movement / pushback). | Key | Description | Type / Unit | Captured at | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------- | ----------- | | `unlimited_fuel` | Unlimited-fuel cheat flag. Encoded as the **string** `"YES"` / `"NO"` (or `null`) despite the name. MSFS only; X-Plane `null`. | string | block-off | | `ramp_weight` | Gross ramp weight at first movement. | number, lbs | block-off | | `blocks_off_time_sim` | In-sim Zulu time at block-off, ISO-8601 (`YYYY-MM-DDTHH:MM:00Z`). | string | block-off | | `blocks_off_time_real` | Real wall-clock time at block-off, ISO-8601 UTC. | string | block-off | | `departure_gate` | Departure parking stand, matched against the pushback position. **MSFS only** (needs airport facility data); X-Plane `null`. | string | takeoff | ### Takeoff Captured at the takeoff trigger (airborne, post-debounce). | Key | Description | Type / Unit | Captured at | | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ----------- | | `taxi_fuel_used` | Fuel burned during taxi-out (block-off fuel minus takeoff fuel, floored at 0). | number, lbs | takeoff | | `takeoff_time_sim` | In-sim Zulu time at takeoff, ISO-8601. | string | takeoff | | `takeoff_time_real` | Real wall-clock time at takeoff, ISO-8601 UTC. | string | takeoff | | `takeoff_weight` | Gross weight at takeoff. | number, lbs | takeoff | | `takeoff_flaps` | Flap handle **detent index** at takeoff (an integer, not a percentage), or `null`. | number | takeoff | | `departure_runway` | Departure runway designator (for example `06L`). Matched client-side, **MSFS only**; X-Plane `null` (derive it server-side from `departure_latitude` / `departure_longitude`). | string | takeoff | | `departure_heading_deviation` | Signed heading minus runway heading at takeoff (±180, positive = clockwise of runway). **MSFS only**. | number, ° | takeoff | | `departure_centerline_deviation` | Perpendicular distance from the runway centerline at takeoff, in **metres**. **MSFS only**. | number, m | takeoff | | `departure_latitude` | Latitude at the liftoff frame. **Every sim.** Lets a VA derive `departure_runway` server-side where the client can't match one (X-Plane). | number, ° | takeoff | | `departure_longitude` | Longitude at the liftoff frame. **Every sim.** | number, ° | takeoff | ### Landing Captured at touchdown, from the landing analyser. | Key | Description | Type / Unit | Captured at | | ------------------- | ------------------------------------------------------------------ | ----------- | ----------- | | `landing_time_sim` | In-sim Zulu time at touchdown, ISO-8601. | string | touchdown | | `landing_time_real` | Real time at touchdown, ISO-8601 UTC. | string | touchdown | | `landing_pitch` | Pitch at touchdown. | number, ° | touchdown | | `landing_g_force` | Vertical G at touchdown (from the analyser). | number, G | touchdown | | `landing_roll` | **Bank / roll attitude** at touchdown — not a roll-out distance. | number, ° | touchdown | | `landing_heading` | Aircraft heading at touchdown (true, 0–360). | number, ° | touchdown | | `landing_weight` | Gross weight at touchdown. | number, lbs | touchdown | | `landing_fuel` | Total fuel weight remaining at touchdown. | number, lbs | touchdown | | `landing_speed` | Indicated airspeed at touchdown. | number, kts | touchdown | | `landing_flaps` | Flap handle **detent index** at touchdown (an integer), or `null`. | number | touchdown | ### Arrival Captured at touchdown or block-on (final stop before shutdown). | Key | Description | Type / Unit | Captured at | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------- | | `arrival_runway` | Arrival runway designator (for example `24R`). **MSFS only**; X-Plane `null`. | string | touchdown | | `arrival_threshold_distance` | Touchdown distance past the runway threshold (from the landing analyser). Populated on **both sims** without facility data. | number, ft | touchdown | | `arrival_heading_deviation` | Signed touchdown heading minus arrival runway heading (±180). **MSFS only**. | number, ° | touchdown | | `arrival_centerline_deviation` | Perpendicular distance from the arrival centerline at touchdown, in **metres**. **MSFS only**. | number, m | touchdown | | `arrival_gate` | Arrival parking stand, matched at the final full stop. **MSFS only**; X-Plane `null`. | string | block-on | | `blocks_on_time_sim` | In-sim Zulu time at gate-in, ISO-8601. | string | block-on | | `blocks_on_time_real` | Real time at gate-in, ISO-8601 UTC. | string | block-on | | `taxi_in_time` | Taxi-in duration (touchdown to final stop) as an **`HH:MM:SS` string**. | string | block-on | ### Summary Captured at completion. | Key | Description | Type / Unit | Captured at | | ------------------- | ---------------------------------------------------------- | ----------- | ----------- | | `total_flight_time` | Total elapsed flight time as an **`HH:MM:SS` string**. | string | completion | | `total_pause_time` | Total accumulated paused time as an **`HH:MM:SS` string**. | string | completion | ## The phase fields There are two distinct phase concepts. 1. **The always-on top-level `phase`** on every position update. It is the **UPPERCASE** API phase: `BOARDING`, `PUSH_BACK`, `TAXI`, `TAKE_OFF`, `REJECTED_TAKE_OFF`, `CLIMB`, `CRUISE`, `DESCENT`, `APPROACH`, `FINAL`, `LANDED`, `GO_AROUND`, `TAXI_TO_GATE` (both `TAXI_IN` and `ARRIVED` collapse to this), `DEBOARDING`, or `UNKNOWN`. While the sim is paused it reports `PAUSED`. This is the only `phase` key on the wire and it is sent on every update, so there is no separate opt-in phase field to enable. 2. **The 15 matrix phase columns**, which decide *when* each field is sent. Their keys are uppercase and keep `TAXI_IN` and `ARRIVED` separate: `BOARDING`, `PUSH_BACK`, `TAXI`, `TAKE_OFF`, `REJECTED_TAKE_OFF`, `CLIMB`, `CRUISE`, `DESCENT`, `APPROACH`, `FINAL`, `LANDED`, `GO_AROUND`, `TAXI_IN`, `ARRIVED`, `DEBOARDING`. `UNKNOWN` is never a column, and `PAUSED` is never a column. While paused, field **selection** still uses the real underlying phase, so per-phase fields keep matching the phase you are actually in even though the top-level `phase` reads `PAUSED`. For the full phase model and the conditions that move a flight between phases, see [Flight Phases](/guide/flight-phases). ## Payload shape On each tick, the fields whose phase set includes the **current** phase are appended after the twelve always-on keys. A representative position update during `cruise`, with a few cruise-phase fields enabled, looks like: ```json theme={null} { "uuid": "f1e2d3c4-5b6a-7890-ab12-cd34ef56ab78", "bid_id": 48213, "phase": "CRUISE", "latitude": -33.9461, "longitude": 151.1772, "heading": 271, "altitude": 37000, "ground_speed": 462, "distance_remaining": 0, "time_remaining": 0, "route": "MARLN H65 RIVET Q29 LIZZI", "network": "offline", "vertical_speed": 0, "indicated_airspeed": 271, "fuel_quantity": 38450, "wind_speed": 24 } ``` The completion PIREP works the same way for the **Submission** column: every Submission-ticked field is merged onto the thirteen always-on completion keys in the `/flights/complete` body. ## Rules worth knowing * A field is appended on a tick only when the live phase is one you ticked for it. * **Live** fields are read from the sim every tick; when the sim can't supply a value the raw default rides along (`0`, `false`, or `""`) — live fields are never blank. * **Milestone** fields are `null` until their capture milestone passes; the same applies to a Submission-ticked milestone field whose milestone never fired. * `block_fuel` and `zfw` on the completion PIREP are **omitted entirely** (not `0`) when never captured. * A few live fields are aliases or derived rather than direct telemetry — `flaps_left_position` / `flaps_right_position` (aliased to `flaps_control`) and `cruise_altitude` (current altitude rounded). The table notes call each one out. * Anything you turn on later starts appearing from the next flight onwards. ## Field availability by simulator Not every simulator populates every field. The general picture: * **MSFS 2020 / 2024 / FSX / P3D (SimConnect):** populate the broadest set, including all engine slots, `engineN_pct_rpm`, `slew_mode`, and native latched `touchdown_*` live fields. * **X-Plane 11 / 12 (UDP DataRef):** populate the same core telemetry, but a few fields are unavailable and report their defaults — `engineN_pct_rpm` is `0`, `slew_mode` is `false`, `landing_rate` is `0` in the air (it holds the canonical touchdown rate after touchdown), the zulu date aliases to the local date, and `altimeter_settings` duplicates `pressure_qnh`. * **Touchdown / departure position** (`touchdown_latitude` / `touchdown_longitude`, `departure_latitude` / `departure_longitude`) is captured on **every sim** — including X-Plane — so a VA can derive the arrival and departure runways server-side where the client can't match one. * **Facility-derived milestone fields** (`departure_runway`, `arrival_runway`, the gate and runway-deviation fields) are matched client-side and are **MSFS only** — `null` on X-Plane; use the touchdown / departure coordinates above to derive them server-side. `aircraft_livery` is populated on MSFS 2024 and X-Plane but empty on MSFS 2020 / FSX / P3D. If a field isn't available from the sim, Stratos sends its default (`0`, `false`, or `""` for live fields, `null` for uncaptured milestone fields). It won't fabricate values.