Results protocol
Every connector has a bridge, running beside your mission control system (MCS), that pulls your account's workflow results: what each workflow run sends to its connections. It makes four calls to the Constellation API. The endpoints keep their original name, /predictions/feed, so bridges already running keep working. All take the header x-api-key with a live key that has predictions:read, and nothing else; GET /predictions/feed also takes a key with only results:read. Bodies are JSON.
| Call | Answers | What it does |
|---|---|---|
GET /predictions/feed?after=<cursor>&limit=<n>&consumer=<name> | 200 {"entries": [{"cursor", "otlp", "oversized"?}], "next", "oldest"} | The finished runs after cursor, oldest first. See Pulling results. |
POST /predictions/feed/checkin | 204 | On start: which system, and what the bridge may write there. See Check-in. |
POST /predictions/feed/deliveries | 204 | After each run applied: what the bridge wrote. See Deliveries. |
GET /predictions/connectors | 200 | What a built-in system's mapping may say and its defaults per template, and under custom the account's own connectors |
The workflow builder shows each check-in and delivery, so an operator can see a connection is live and what each run wrote without opening their system.
| Status | Code | Action |
|---|---|---|
401 | auth_failed | The key is missing or unknown. |
403 | insufficient_scope, live_key_required | Use a live key with predictions:read. |
403 | plan_required | A Lattice or COSMOS check-in, or a feed read holding results for one, on a plan below Enterprise. The body names the plan and feature. |
404 | unknown_cursor | Fetching a page of an entry the account no longer holds. Pull from your last cursor instead. |
404 | unknown_run | A delivery report names a run the account does not have. |
410 | run_data_expired | The entry's stored data expired. Pull on from the next cursor. |
422 | A body that breaks the rules below; the body names the field. | |
429 | too_many_consumers | The account already has 50 connections. Reuse one, or remove a custom connector. |
5xx, or a dropped connection | Retry. |
Pulling results
GET /predictions/feed answers the next finished runs after after (empty: from the start), oldest first, at most limit, from 1 to 20 (default 20). A run can be several MB, so pull 1 at a time. A page also stops at 8 MiB, so it can hold fewer entries than limit: carry on from next. An entry over 8 MiB on its own comes alone, with oversized: true; read it with page_records (see Paging a large run), since a whole entry over 10 MiB cannot be sent at all.
With consumer, each entry holds only the resources addressed to that connection, and Constellation records how far that connection has read. An entry with nothing for it has no resources, and its cursor still moves you past it. next is the last entry's cursor, or after when there are none.
Cursors
A cursor is <finish time %Y%m%dT%H%M%S.%f>#<run_id>: cursors sort as strings, in the order runs finished. Treat a cursor as opaque apart from that ordering, and take the run id from the resource's constellation.run_id, not from the cursor.
Keep the last cursor you applied, in your system if it can hold one, and pull after it. Never move past a run you failed to apply.
First start
With no kept cursor, a bridge reads GET /predictions/feed?from=latest&consumer=<name> first. It answers no entries and a next just before the newest run with something for that connection; pull after it, so the bridge applies that run and none of the history before it. An API before contract 1.5.0 ignores from and answers a page of entries instead. The official bridges and SDKs then refuse to start, with the API ignored GET /predictions/feed?from=latest, so a first start cannot find the newest run: this bridge needs an API serving contract 1.5.0 or later, rather than apply the history. Do the same in your own bridge. To apply the whole history on purpose, pull after empty instead (BACKFILL=1 in the SDK Bridge classes and Go results.NewBridge; the Yamcs, Lattice and COSMOS bridges always start at the newest run).
Oldest
Constellation keeps each entry for 7 days after it was published. oldest is the oldest cursor it still holds, or null when it holds none. When your kept cursor sorts before oldest, the runs in between expired while your bridge was offline: log that, and read on from the oldest.
Paging a large run
A run can carry thousands of items. Add page_records=<n> (1 to 5,000) to the call, and an entry with more records than that arrives in pages: the first in the entry, with next_page. Fetch the rest with
GET /predictions/feed?cursor=<the entry's cursor>&page=<next_page>&consumer=<name>&page_records=<n>
which answers {"cursor", "otlp", "next_page"?}, until there is no next_page, adding each page's records to the resource with the same attributes. Apply the run once, whole; never a page of it. Without page_records, an entry is always whole.
A results entry
otlp is an OTLP/JSON logs document (ExportLogsServiceRequest): one resourceLogs per mission control output of the run, and one log record per item. The record's body is the item as an OTLP AnyValue: kvlistValue, arrayValue, stringValue, intValue as a string, doubleValue or boolValue.
| Resource attribute | Meaning |
|---|---|
constellation.workflow | The workflow's slug |
constellation.workflow_version | The version that ran |
constellation.template | What the run answers, from the step that decides it: pass-yield, rain-fade-swap, antenna-capacity, modcod-plan, audit-ledger or rfi-watch. It tells a run with no items apart, such as "no swaps advised". |
constellation.run_id | The run, such as run_20261106T223001_95bf04bc |
constellation.window.from, constellation.window.to | The window the run is the whole answer for (RFC 3339) |
constellation.connection | The connection this output is for |
constellation.system | yamcs, cosmos, lattice or custom |
constellation.output | JSON: the output as the bridge applies it, {connection, system, mapping_version, mapping, tokens}. A custom connector's settings are mapping.settings, every one present. |
Each log record carries constellation.schema, the item shape, today constellation.item/v2. Read the one shape you were built for, and skip and log a run in any other, so an old bridge never misreads newer results.
A run is the whole answer for its window
A run's items for a connection are everything that workflow version says about its window, at that time. A later run of the same workflow over an overlapping window supersedes it there:
- an item the later run carries again, with the same
entity.id, is updated; - an item inside the later run's window that it no longer carries is withdrawn: the forecast changed, such as a pass now below the workflow's cut, or a swap no longer advised;
- an item outside the later run's window is untouched.
A run with nothing to say is still published, its resource with no records, so the window it answers for is cleared. A rain-fade-swap run with no swaps advised withdraws every swap you wrote for that workflow inside its window. A pass whose LOS is past is history: leave it, or let your system age it out.
Items
{
"entity": {
"type": "pass", "id": "pass_1f0c9a2b7e41", "link_id": "SITE-000000000001__ant0:sat-4017",
"satellite_id": "sat-4017", "ground_station_id": "SITE-000000000001",
"antenna_id": "SITE-000000000001__ant0", "source": "computed",
"track": [
{"t": "2026-11-06T23:16:00+00:00", "latitude_deg": 31.2, "longitude_deg": -116.9},
{"t": "2026-11-06T23:23:00+00:00", "latitude_deg": 48.6, "longitude_deg": -104.3}
]
},
"target_at": "2026-11-06T23:16:00+00:00",
"until": "2026-11-06T23:23:00+00:00",
"value": {"p10": 46.0, "p50": 46.0, "p90": 46.0},
"explain": {
"passes": {"value": 41.2, "unit": "deg", "source": "orbit"},
"weather": {"value": {"p10": 0.6, "p50": 0.6, "p90": 0.6}, "unit": "dB", "source": "model:weather-attenuation:…"},
"expected_gb": {"value": {"p10": 46.0, "p50": 46.0, "p90": 46.0}, "unit": "GB", "source": "expected_gb"}
},
"workflow_version": 12
}
| Field | Meaning |
|---|---|
entity.type | pass (one satellite over one antenna, AOS to LOS), antenna (an antenna-capacity day), or link (an antenna's view of a satellite) |
entity.id | Stable for the thing it names, so writes keyed on it update in place: pass_ and 12 hex digits for a computed pass, the provider's id for a booked one, the antenna id for an antenna. At most 128 characters of [A-Za-z0-9._:|-]. |
entity.satellite_id, antenna_id, ground_station_id | Ids from the account's topology config, unique within the account. A system with its own ids needs a mapping, as a setting or on its side. |
entity.link_id | <antenna_id>:<satellite_id> |
entity.source | computed (from orbits) or gsaas (booked with a provider, with entity.cancel_deadline_utc) |
entity.track | On a pass: the ground under the satellite from AOS to LOS, up to 8 points in time order, AOS and LOS among them |
target_at, until | RFC 3339 in UTC with an offset: a pass's AOS and LOS, or an antenna day's start and end. Parse any precision. |
value | The workflow's output, below. Absent when nothing priced the item, such as a pass on a radio with no RF data. |
explain | The ledger: each step that wrote something for the item, keyed by the step's id, as {value, unit, source}. The pass's max elevation is the entry with source: "orbit". |
series | On a MODCOD plan: [{t, value: {modcod, sinr_db}}], each change of MODCOD and when |
severity, action | On a rain-fade swap, below, or an rfi-watch reroute. With an approve policy, action_status too |
workflow_version | The version that produced it |
| Template | Items | value |
|---|---|---|
pass-yield | Passes | Expected GB: {p10, p50, p90} |
rain-fade-swap | Passes at risk only, each with an action | Expected GB on the pass at risk |
antenna-capacity | One antenna item per antenna per UTC day | {passes, sellable_min, p10, p50, p90} (GB) |
modcod-plan | Passes with a series | Expected GB and modcod_changes |
audit-ledger | Past passes | The ledger: {possible_gb, delivered_gb, status} |
rfi-watch | Links with RF interference past a threshold, each with a reroute action | {p10, p50, p90, lock_loss_risk}: the worst interference in dB, and the share of steps it costs lock |
Except on rfi-watch, quantiles are the GB a pass is forecast to deliver: p10 is the low case (nine passes in ten deliver at least this), p50 the middle and p90 the high case. Any of them may be equal; none is negative.
A rain-fade swap's action, with severity: "warning":
{
"verb": "swap", "mode": "suggest",
"from": "pass_1f0c9a2b7e41", "to": "pass_7a03c1d9e2f0",
"to_antenna_id": "SITE-000000000001__ant1", "to_at": "2026-11-07T01:02:00+00:00",
"deadline": "2026-11-06T23:01:00+00:00", "gain_gb_p10": 12.4
}
from is the pass at risk. to, to_antenna_id and to_at (the backup pass's AOS) name the best backup within 6 hours on an antenna not already tracking another pass then, all three null when there is none. deadline is the last moment to act, the provider's cancellation lead before AOS. gain_gb_p10 is what the swap gains in the low case. mode: "suggest" means advice for an operator, never an instruction to act.
When the workflow holds actions for approval, an item carries action_status: pending or rejected with no action, or approved with the action, mode: "approve". An approved action is an instruction a person has approved; carry it out before its deadline.
action | action_status | What it is |
|---|---|---|
| Present | Absent | Advice (mode: "suggest") |
| Present | approved | An instruction: a person approved it. Carry it out (cancel the pass, book the backup). |
| Absent | pending | Held for approval. The action is not sent until it is approved. |
| Absent | rejected | Decided against: the original pass stands. |
A held item also carries action_id and, once decided, decision_id:
| Field | What it names |
|---|---|
action_id | The action: the same verb on the same entity to the same target has the same action_id in every run of the workflow, whatever its status |
decision_id | One decision on that action. A standing approval keeps its decision_id in every run that sends it; a new approval of the same action gets a new one |
Approving publishes the run again with the approved action on its item, and later runs send it again while the approval stands, so a bridge remembers what it acted on. Key that memory on decision_id, falling back to entity.id|verb|to on an item without one: a standing approval is then acted on once, and a re-approval is acted on again. Forget a key 7 days after its action expires (the latest of the item's target_at, until and the action's deadline); no run sends it after that. The Bridge classes in the SDKs do this for you. Only an item with neither action nor action_status is a plain forecast pass. Treat a status you do not recognise as held. action_state(item) in the Python SDK and actionState(item) in the TypeScript SDK read all of this (see SDKs).
Check-in
{
"consumer": "yamcs-bridge",
"system": "yamcs",
"target": "Yamcs 5.14.0 instance simulator",
"bridge_version": "0.7.0",
"can": {"events": true, "timeline": true, "parameters": true, "buckets": true},
"widget": {"installed": true, "version": "0.7.0"}
}
consumer is a lowercase slug (a-z, 0-9, -, at most 63 characters). target, at most 200 characters, says what the bridge writes to. can and widget are for the built-in systems. A custom connector checks in with system: "custom" and adds manifest, and its consumer is the manifest's name. A check-in holds no credentials: only what the bridge found it may do.
Deliveries
{
"consumer": "example-mcs",
"run_id": "run_20261106T223001_95bf04bc",
"cursor": "20261106T223053.200101#run_20261106T223001_95bf04bc",
"applied": {"passes": 12, "swap_alerts": 1},
"target": "Example MCS"
}
applied is up to 20 counts, each a whole number, named as you like: the workflow builder shows them as "wrote 12 passes, 1 swap alert". Report once per run you applied, after applying it. One name is read on its own: acted, the number of approved actions the bridge carried out in your system. Once a run's report counts any, the Platform shows its approved actions as carried out by your bridge.