Skip to main content

The shared response shape

Every forecast the API returns comes as items in one shape: what the item is about, when, its value with a range, the ledger that explains it, and the version that produced it. Workflow runs answer in it, and so does a model read with format=items. Whatever could not be answered is listed beside the items, never dropped without a word.

The same items reach your mission control system (MCS) as workflow results, through the results protocol, and Amazon S3 and webhooks receive them as GET /predictions returns them; Grafana Cloud receives their values as metrics.

An item​

Example item (illustrative values):

{
"entity": { "type": "pass", "id": "pass_1f0c9a2b7e41", "link_id": "ant-1:sat-1", "satellite_id": "sat-1", "ground_station_id": "gs-1", "antenna_id": "ant-1" },
"target_at": "2026-11-05T14:02:00+00:00",
"until": "2026-11-05T14:10:00+00:00",
"value": { "p10": 38.6, "p50": 39.6, "p90": 40.6 },
"explain": {
"snr": { "value": { "p10": 11.5, "p50": 11.5, "p90": 11.5 }, "unit": "dB", "source": "physics:clear-sky-budget" },
"expected_gb": { "value": { "p10": 38.6, "p50": 39.6, "p90": 40.6 }, "unit": "GB", "source": "capacity*success" }
},
"workflow_version": 3
}
FieldMeans
entityWhat the item is about, with its IDs: a pass, a link, or the antenna, satellite or ground station a sum is for
target_at, untilThe time the value is for, and the end of its span when it has one
valueThe output's columns. One with a range adds p10, p50 and p90; any other adds itself under its name
explainThe ledger: per workflow node (or, on a model read, per field), its value at the pass's peak, unit and source
quantity, unitOn a model read with format=items: what value measures and its unit. snr_db (dB), rx_power_dbm (dBm, an optical link), attenuation_db (dB), p_free (share), rfi_penalty_db (dB) or p_track (probability)
workflow_version or model_release_idWhat produced the item: a workflow's version, or a model release. Never both
series, severity, actionOptional. A time-tagged schedule such as MODCOD changes; info, warning or critical; a recommendation, such as a swap, with its deadline
action_statusOn an item whose recommendation is held for approval: pending, approved or rejected
action_id, decision_idOn a held recommendation: the action, the same in every run that suggests it, and once it is decided, the decision
noteOptional. What the recommendation comes to, as a sentence for a person

A source names what priced the node: a model as model:<family>:<release id>, or a physics baseline, physics:clear-sky-budget or climatology, followed by why its model was not used, such as :plan_required:learned_corrections or :unavailable:<code>. A source that starts with unavailable:, such as unavailable:invalid_answer, means that node could not price the item.

Value and range​

APIOn the Platform's screensMeans
p50ExpectedThe middle forecast
p10 to p90The range8 in 10 outcomes land inside it
p10The low caseWhat to plan on when the downside matters

The range is never invented: a model that gives one value answers p50 alone (weather attenuation's attenuation_db, demand's p_free, rfi's rfi_penalty_db, ssa's p_track), and a lane with one value, such as the clear-sky link budget, repeats it at all three. In a workflow, each quantile is a band rather than a joint probability: p10 pairs every lane's pessimistic tail. See Reading a result.

What could not be answered​

ResponseFieldShape
A model readentity_errors[{"entity_id", "code", "message"}] beside the items in a 200. An entity can be in both, when its item is a stored one and no fresh forecast was made. Branch on code
A workflow rundeclined{"<antenna>:<satellite>": "<code>"}: each pair the run left out, with why, such as band_mismatch
An audit rununmatched_logs, skipped_logsLogged contacts no pass matched, and how many could not be read

Versions​

Every number can be traced to what made it:

  • On each item: workflow_version, or model_release_id.
  • On a run: workflow, workflow_version, network_config_version, catalog_version when your fleet came from the catalog, orbit_snapshots, lanes, the window (from, to, step_s), and scenario_id and dataset when it has them.
  • On a model read: model_family, captured_at, and model_release_id when every item shares one.

The Platform's version line under each number reads these fields.

A run's envelope​

A workflow run read with GET /predictions?run_id= wraps its items with its run_id, status, created_at and the fields of the request it ran, such as workflow and deliver, plus:

FieldMeans
stageWhere a running run is; see Long runs
queue_positionOn a queued run: how many of the workspace's runs must finish before it starts, 0 once it is next
deliverfalse for a test run or a scenario run, which deliver nothing
act_modeWhat the run did with recommendations: live, shadow or off; see From trial to sending
feed_cursor, deliveriesWhere its results went: its entry in your workflow results, and what each connector or destination reported
superseded_byA newer run that delivered, or is delivering, in its place
error, or cancelled_by and cancelled_atWhy it failed, or who stopped it and when
next_pageWith page_records, the next page of items

An audit run also carries totals, as by_station and overall. Each field of each endpoint is in Predictions.