Orbit determination runs

A run fits the orbit to the fixes of an arc and predicts it for the day after.

run = client.runs.request(satellite, "2026-10-01T00:00:00Z", "2026-10-02T00:00:00Z")
run = run.wait()  # RunFailed if it failed, WaitTimeout if it takes too long
client.runs.list(satellite)  # newest first
client.runs.get(run.id)

The arc is between 3 and 72 hours; a day is a good choice. A run is queued, then running, then succeeded or failed; a day of data takes about ten seconds.

Reading a run

print(run.status, run.accepted, run.weighted_rms, run.flags)
print(run.arc_start, run.arc_end, run.mass_kg)
run.download("oem", "orbits/")  # oem, uncertainty, residuals, result
run.report("reports/")  # the run as one HTML page with its charts
run.raw["fixes"]  # anything of the API's answer not modelled

accepted tells you whether the run can be trusted without a closer look. It compares figures of the run with fixed limits of its profile: how well the orbit fits the fixes, how many fixes were left out as outliers, how many iterations were needed and the longest gap in the data. A run that is not accepted still has its products. Look at its residuals before you use its orbit: an unreported manoeuvre or wrong spacecraft properties are the usual causes.

weighted_rms is the fit’s residuals over the sigma the fixes were weighted with: near 1 is right.

flags list what deserves a look in a run that passed:

  • possible_unmodelled_manoeuvre: the small accelerations the service estimates every half hour, to take up what its force model lacks, came out many times larger than expected somewhere in the arc. Something pushed the satellite that the model does not know: most often a burn nobody reported, sometimes a geomagnetic storm. The flag (in run.raw) gives its span and equivalent_delta_v_m_s, the size of the push as a velocity change. The orbit is usable; report the burn (Manoeuvres and plans) so that later runs model it.

  • prediction_outside_uncertainty: the run’s orbit lies more than three standard deviations from what the run before predicted for the same hours, radially or along the track. The prediction did not foresee something: a burn, a change in the atmosphere. On healthy arcs about one run in eight raises it by chance; a burn raises it by far more.

The run before. A run that shares time with the accepted run before it compares the two (run.raw["self_check"]): how far that run’s prediction lay from this run’s fitted orbit 1, 6, 12 and 24 hours after its arc, and how far the two fitted orbits lie apart where they overlap. The diagnostics have the same every five minutes (Diagnostics and trends).

A failed run raises RunFailed from wait(), with the API’s error code:

Code

Meaning

What to do

invalid_tracking_data

The fixes inside the arc could not be used

Check the file and the arc

estimation_failed

No orbit could be fitted to the fixes

Check the spacecraft properties and that the arc holds no manoeuvre; try a shorter arc

internal_error

The fault is ours

Nothing; we are told. Contact us with the run’s id

A request that cannot be accepted is refused at once (InvalidRequest), for example when the arc holds no tracking data or the satellite has no properties yet.

Profiles and settings

A run is made by a profile, the kind of determination on offer. The default, leo-gnss-v4, suits most satellites in low orbit as it is: the drag coefficient estimated in steps over the arc, small empirical accelerations every half hour, and a predicted uncertainty that holds the atmosphere’s error (measured against ESA’s precise orbits of Swarm: about two thirds of the prediction’s errors within one standard deviation, all but a few within three).

for profile in client.profiles():
    print(profile.name, profile.default, profile.description)
    print("  settings:", ", ".join(profile.settings))

Each profile offers named settings: the same determination with one thing changed, such as segments-60min (the empirical accelerations per hour, not per half hour), sigma-2m (the fixes trusted to 2 m, not 1 m) or no-empirical. Name one in a run or a schedule:

client.runs.request(satellite, arc_start, arc_end, setting="segments-60min")
client.runs.request(satellite, arc_start, arc_end, profile="leo-gnss-v3")

To find out whether a setting suits your satellite better, compare them over the same arc (Comparing settings).

Custom settings

Where a named setting is not enough, an expert chooses the estimation’s figures, in place of a setting. It is a feature of your tier (od_custom_settings in client.me().features; without it FeatureNotIncluded). What is left out stays the profile’s.

default = next(p for p in client.profiles() if p.default)
for setting in default.custom_settings:
    print(setting.name, setting.value, setting.minimum, setting.maximum)

run = client.runs.request(
    satellite,
    arc_start,
    arc_end,
    custom={"segment_minutes": 45, "along_track_sigma_m_s2": 5e-9, "gravity_degree": 90},
).wait()
print(run.setting, run.custom)  # "custom", the settings given

Setting

Meaning

segment_minutes

Length of the segments of the empirical accelerations (5 to 720)

fixes_sigma_m

Standard deviation the fixes are weighted with, per axis

fixes_step_s

One fix is used per this many seconds (1 to 600)

estimate_empirical

Whether along-track and cross-track empirical accelerations are estimated

along_track_sigma_m_s2, cross_track_sigma_m_s2

Their a priori standard deviations

drag_coefficient_sigma

A priori standard deviation of the drag coefficient, around your properties’ value; left out: free

drag_step_hours

The drag coefficient estimated in steps of this length (1 to 72 hours) instead of once for the arc; steps shorter than about two orbits predict worse

estimate_antenna

Which components of the antenna offset are refined: "R", "N", "RN" or "" for none

edit_threshold

Editing threshold k; 0: no fix is left out

prediction_hours

Length of the predicted ephemeris (1 to 72)

consider_drag_sigma

Uncertainty of the drag coefficient added to the predicted covariance

consider_drag_share

The same as a share of the predicted drag coefficient (0.075 in leo-gnss-v4); consider_drag_sigma wins where both are given

covariance_scale

k: the ephemeris’s formal standard deviations are multiplied by it

gravity_degree

Degree and order of the gravity field (2 to 120)

A value outside a setting’s limits is refused. A run made this way shows "custom" as its setting and is judged by the profile’s acceptance limits like any other.