Skip to main content

Prediction workflow

Difficulty: Intermediate. Time: about 20 minutes. Needs: the console for part one; a provisioned API key for part two.

SNR forecasting is the production prediction path today: a trained snr model family served per tenant. You will read forecasts the operator way in the console, then build the automation way with GET /predictions.

Part one: the console panel​

  1. Select a feeder link (or a satellite or gateway) on the globe.
  2. Open the Predictions tab on the entity card.
  3. Read the SNR forecast next to the telemetry sparkline for the same metric; keeping forecast and stored truth adjacent is the point of the layout.

What to notice while you read:

  • Source labeling. Every forecast names what produced it: the production model and its fidelity tier, the general physics-anchored baseline (the keyless fallback for guests), or a clearly labeled illustrative stub for domains without a production backend yet. A screenshot of this panel can never oversell what was computed.
  • Tiers are a plan feature. Bronze ships with Standard; silver and gold with Pro; custom models with Enterprise. The mapping is enforced client-side by your entitlements; asking for a tier your plan lacks gets an upgrade hint, not a permission error. See Plans and billing.
  • Freshness is visible. Forecasts refresh on 60-second buckets with stale-while-revalidate: an expiring forecast keeps rendering with its age shown while a fresh one is fetched.

Expected outcome: a forecast with a named source and tier, whose age indicator you can watch roll over on the next refresh bucket.

Part two: the API polling variant​

Automation reads the same model through GET /predictions. Two modes, one endpoint:

Cached (default)​

curl -sS -H "x-api-key: $CONSTELLATION_API_TOKEN" \
  "https://api.constellation.space/predictions?model_family=snr&link_ids=GS-SEA-1:SAT-0012"

Returns a PredictionSet captured at some captured_at, one item per link with p50, p10, and p90 SNR values, the model version, and the horizon. Right for dashboards and periodic polling.

Live​

curl -sS -H "x-api-key: $CONSTELLATION_API_TOKEN" \
  "https://api.constellation.space/predictions?model_family=snr&link_ids=GS-SEA-1:SAT-0012&live=true"

Runs inference on request and returns a provenance block per response: serving backend, model version, feature source, the exact telemetry window the features were built from, how many telemetry points backed it, and the fill policy. Right when a forecast will drive a decision and needs receipts. See Data model for the field-by-field breakdown.

Polling rules that keep you inside the limits​

  • Batch links into one request: link_ids takes up to 100 ids (more returns 400 too_many_link_ids), so one fleet poll per tick beats one request per link.
  • Poll cached predictions at a period matched to their refresh, not hot; per-tenant rate limiting is 60 requests per minute with a 10 per second burst.
  • On 429 or 503, honor Retry-After; both are retryable, unlike 401.
  • There is no POST /predictions and no webhook push; polling is the contract. See Predictions API.

Expected outcome: a script that fetches your fleet's link forecasts in one request per tick and logs p50/p10/p90 per link.

Troubleshooting
  • Empty items on the cached path: no prediction set has been captured for those links yet; try live=true, and verify your link_ids match the link identities in your topology.
  • 400 too_many_link_ids: you exceeded the 100-link cap; page your fleet into chunks.
  • Console panel shows the baseline instead of the model: the console has no tenant API key configured for live access, or you are in guest mode; the baseline is the honest keyless fallback.
  • Forecast seems frozen for up to a minute: that is the 60-second refresh bucket working as designed; the age label tells you exactly how old the number is.

Where next​