SSA pass forecast
| Value | |
|---|---|
model_family | ssa |
| Version | v1 |
| Predicts | The contact a satellite is in at one time, the orbit error behind it, and p_track |
| Time | One instant, within 7 days of now |
| Entity | A satellite, over one ground station or every station in your network config |
| Reads | Your network config and the satellite's orbit; on Operator and above, carrier_locked telemetry to calibrate p_track |
Overview
The space situational awareness (SSA) pass forecast tells you whether your antenna will find a satellite at the start of a pass and keep it in the beam until the end. You name a satellite and a time, and get back each contact the satellite is in at that time, one per antenna that can work it. A contact is one pass over one antenna, from AOS to LOS.
Each contact has its pass window, its peak elevation and range, how far off the satellite's published orbit may be, and p_track, the chance the antenna holds it.
Orbit error matters most on narrow beams. A Ka-band dish has a beam a fraction of a degree wide, so for a low satellite an along-track error of a kilometre or two (illustrative) can put it outside the beam; an S-band beam is several times wider, so the same error costs almost nothing.
Intended use
- Flagging contacts on higher bands, such as Ka-band and X-band, whose orbit is too uncertain to point from.
- Choosing between contacts: a lower
p_trackis more likely to be lost to pointing. - Weighting expected data by the chance the contact holds.
- Recommended prediction horizon. Test it from now to 2 days ahead. Element sets grow stale over time, so pointing becomes less accurate.
Inputs
| Parameter | Description |
|---|---|
satellite_id | Required. A satellite in your network config. |
at | Required. A time within 7 days of now, past or future. |
ground_station_id | Optional. Limits the answer to one ground station. |
The model reads your stations, antennas and the satellite's downlink radios from your network config, and the satellite's orbit from our catalog, or from its tle if you give one.
To price p_track, an antenna needs its beam. Set half_power_beamwidth_deg on its frequency range if you know it, or antenna_diameter_m so the model can estimate it.
Outputs
One item per contact in progress at at.
| Field | Unit | Description |
|---|---|---|
pass_start_at, pass_end_at | UTC | When the satellite rises above the antenna's mask and sets below it. |
max_elevation_deg | deg | Peak elevation of the contact. |
slant_range_km | km | Distance to the satellite at the peak. |
in_track_error_km | km | How far along its track the satellite may be from its published orbit: p50, the median, and p90, which 9 in 10 stay within. |
orbit_timing_error_s | s | The same error as time: how early or late the satellite may arrive. |
error_basis | none | measured when our measured orbit data covers this orbit, or default when the nearest measured case is widened to cover it, as for a tle you supply. |
p_track | 0 to 1 | The chance the antenna holds the satellite in its beam from AOS to LOS. |
p_track_basis | none | basis is calibrated when p_track has learned from your antenna's telemetry, else default; contacts is how many contacts it rests on; bound is ceiling or floor when the value sits at the edge of the error table. |
orbit | none | The orbit used, its age in hours, and stale when it is 72 h old or more. |
{
"ground_station_id": "gs-1",
"ground_antenna_id": "ant-1",
"satellite_id": "sat-1",
"value": {
"pass_start_at": "2026-11-05T10:00:00Z",
"pass_end_at": "2026-11-05T10:08:12Z",
"max_elevation_deg": 58,
"slant_range_km": 639,
"in_track_error_km": { "p50": 0.9, "p90": 2.82 },
"orbit_timing_error_s": { "p50": 0.12, "p90": 0.37 },
"error_basis": "measured",
"p_track": 0.62,
"p_track_basis": { "basis": "default", "contacts": 0 },
"orbit": { "source": "gp", "age_h": 30, "stale": false }
}
}
One item from the response, with illustrative values. Some fields are left out.
A time outside every contact returns no items.
How to read p_track
p_track is in beta. It is being validated against real contacts, and its values can change between releases.
p_track is a probability: of contacts given 0.8, about 8 in 10 should hold. A contact holds when the receiver keeps carrier lock from acquisition of signal to loss of signal, and fails when it loses lock.
Before calibration, p_track comes from the antenna's beam and the orbit error at the peak of the pass. After calibration, it also moves toward how often your antenna actually held contacts like this one. With few contacts on record it stays near the first value. With many, it follows your antenna's record.
Explore p_track
Drag the fields to see how the beam, the range and the orbit error set p_track, and how your antenna's record moves it.
- Beamwidth
- 0.218°
- Hold distance
- 1.22 km
- Static
- 0.63
The shaded area is the share of in-track errors that keep the satellite within half the beam. This page draws the error as a smooth curve through your p50 and p90; the served model reads the full measured error table.
p_track is null when the model has no beam for the antenna, or when the orbit is 7 days old or more at the pass.
Calibration
On Operator and above, the model learns from your telemetry each night: it adjusts each antenna's p_track and its beam to what the antenna actually did. Send these fields on each pass:
| Telemetry field | Used for |
|---|---|
carrier_locked | Whether the antenna held the contact. Required: a contact from a receiver that never reports it is not counted, and with none counted p_track stays at its value before calibration. |
c_n0_dbhz or es_n0_db | The signal level. |
tracking_error_az_deg, tracking_error_el_deg | The beam. |
track_mode | Whether the antenna was on program track or autotrack. |
Request forecasts
curl --fail-with-body -sS -G \
-H "x-api-key: $CONSTELLATION_API_KEY" \
"https://api.constellation.space/predictions" \
--data-urlencode "model_family=ssa" \
--data-urlencode "satellite_id=sat-1" \
--data-urlencode "at=$(date -u +%Y-%m-%dT%H:%M:%SZ)"
at names a moment, not a pass: any time inside a contact returns that contact. Set to now, as above, it returns a contact only while one is in progress; for a coming pass, set at to a time inside it, from GET /topology/passes. To follow several passes, send one request per pass. A request needs a key with predictions:read; a test key is refused with 400 sandbox_model_family_unsupported. From an AI agent, call get_predictions on the MCP server with the same parameters.
With format=items, each item's value.p50 is p_track (quantity p_track, unit probability), with the other fields in explain. Its target_at is the pass start, or the pass end when the start falls before the search window, else when the forecast was made.
Declines
| Reason | Cause |
|---|---|
not_in_network_config | The satellite or station is not in your latest network config. |
band_mismatch | No antenna can receive the satellite's downlink. |
no_orbit_data | We have no recent orbit for the satellite. Give it a tle. |
orbit_propagation_failed | The orbit could not be propagated to at. |
prediction_unavailable | The forecast could not be computed in time. Retry. |
Limitations and known failure modes
p_trackis in beta. Use it to rank passes, and check it against your own outcomes.- Before calibration,
p_trackcounts orbit error only, so it can read high where the mount, receiver or weather decide the pass. - Manoeuvres since the latest orbit are not in the error.
- Pass times are geometric. Your receiver locks after AOS and loses lock before LOS.
- Coverage. Every orbit gets orbit error and
p_track, starting from orbit data we have measured across a range of orbit heights. Where none covers an orbit, the nearest case is widened, anderror_basisisdefault. As your antenna's lock record builds up, calibration bringsp_trackcloser to what your antenna actually does.
Changelog
| Version | Change |
|---|---|
| v1 | One contact per antenna at a time you name: pass window, geometry, orbit error, and p_track, calibrated from your antenna's telemetry. |
Related
- Space situational awareness for operators: orbit data, TLE age and pass prediction error
- Predict satellite pass data volume: where
p_trackfits in expected GB per pass