Skip to main content

SSA pass forecast

Value
model_familyssa
Versionv1
PredictsThe contact a satellite is in at one time, the orbit error behind it, and p_track
TimeOne instant, within 7 days of now
EntityA satellite, over one ground station or every station in your network config
ReadsYour 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_track is 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​

ParameterDescription
satellite_idRequired. A satellite in your network config.
atRequired. A time within 7 days of now, past or future.
ground_station_idOptional. 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.

FieldUnitDescription
pass_start_at, pass_end_atUTCWhen the satellite rises above the antenna's mask and sets below it.
max_elevation_degdegPeak elevation of the contact.
slant_range_kmkmDistance to the satellite at the peak.
in_track_error_kmkmHow 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_ssThe same error as time: how early or late the satellite may arrive.
error_basisnonemeasured 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_track0 to 1The chance the antenna holds the satellite in its beam from AOS to LOS.
p_track_basisnonebasis 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.
orbitnoneThe 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​

note

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.

half beam: 1.22 km0 kmin-track error →
0.63p_track
default: no contacts on record, so the static value is served
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 fieldUsed for
carrier_lockedWhether 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_dbThe signal level.
tracking_error_az_deg, tracking_error_el_degThe beam.
track_modeWhether 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​

ReasonCause
not_in_network_configThe satellite or station is not in your latest network config.
band_mismatchNo antenna can receive the satellite's downlink.
no_orbit_dataWe have no recent orbit for the satellite. Give it a tle.
orbit_propagation_failedThe orbit could not be propagated to at.
prediction_unavailableThe forecast could not be computed in time. Retry.

Limitations and known failure modes​

  • p_track is in beta. Use it to rank passes, and check it against your own outcomes.
  • Before calibration, p_track counts 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, and error_basis is default. As your antenna's lock record builds up, calibration brings p_track closer to what your antenna actually does.

Changelog​

VersionChange
v1One contact per antenna at a time you name: pass window, geometry, orbit error, and p_track, calibrated from your antenna's telemetry.