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
}
| Field | Means |
|---|---|
entity | What the item is about, with its IDs: a pass, a link, or the antenna, satellite or ground station a sum is for |
target_at, until | The time the value is for, and the end of its span when it has one |
value | The output's columns. One with a range adds p10, p50 and p90; any other adds itself under its name |
explain | The ledger: per workflow node (or, on a model read, per field), its value at the pass's peak, unit and source |
quantity, unit | On 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_id | What produced the item: a workflow's version, or a model release. Never both |
series, severity, action | Optional. A time-tagged schedule such as MODCOD changes; info, warning or critical; a recommendation, such as a swap, with its deadline |
action_status | On an item whose recommendation is held for approval: pending, approved or rejected |
action_id, decision_id | On a held recommendation: the action, the same in every run that suggests it, and once it is decided, the decision |
note | Optional. 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
| API | On the Platform's screens | Means |
|---|---|---|
p50 | Expected | The middle forecast |
p10 to p90 | The range | 8 in 10 outcomes land inside it |
p10 | The low case | What 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
| Response | Field | Shape |
|---|---|---|
| A model read | entity_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 run | declined | {"<antenna>:<satellite>": "<code>"}: each pair the run left out, with why, such as band_mismatch |
| An audit run | unmatched_logs, skipped_logs | Logged 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, ormodel_release_id. - On a run:
workflow,workflow_version,network_config_version,catalog_versionwhen your fleet came from the catalog,orbit_snapshots,lanes, the window (from,to,step_s), andscenario_idanddatasetwhen it has them. - On a model read:
model_family,captured_at, andmodel_release_idwhen 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:
| Field | Means |
|---|---|
stage | Where a running run is; see Long runs |
queue_position | On a queued run: how many of the workspace's runs must finish before it starts, 0 once it is next |
deliver | false for a test run or a scenario run, which deliver nothing |
act_mode | What the run did with recommendations: live, shadow or off; see From trial to sending |
feed_cursor, deliveries | Where its results went: its entry in your workflow results, and what each connector or destination reported |
superseded_by | A newer run that delivered, or is delivering, in its place |
error, or cancelled_by and cancelled_at | Why it failed, or who stopped it and when |
next_page | With 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.