Predictions

Predictions API

Get SNR degradation and queue utilization predictions for nodes and their links.

GET /api/v1/predictions/{node_id}

Get predictions for a specific node’s associated links.

Request

GET /api/v1/predictions/\{node_id\}
Authorization: Bearer <token>

Path Parameters

Name	Type	Description
node_id	string	The target node identifier

Query Parameters

Name	Type	Default	Description
use_cache	boolean	true	Use cached predictions if available

Example Request

curl -X GET "https://api.constellation-io.com/api/v1/predictions/sat-001" \
  -H "Authorization: Bearer $TOKEN"

Response

{
  "node_id": "sat-001",
  "timestamp": "2026-01-16T20:00:00Z",
  "cached": false,
  "links": [
    {
      "src": "sat-001",
      "dst": "gs-001",
      "horizons": [
        {
          "horizon_minutes": 1,
          "predictions": {
            "snr_degradation": {
              "current_db": 25.5,
              "predicted_db": 24.8,
              "confidence": 0.92
            },
            "queue_utilization": {
              "current_utilization": 0.65,
              "predicted_utilization": 0.68,
              "confidence": 0.89
            }
          }
        },
        {
          "horizon_minutes": 3,
          "predictions": {
            "snr_degradation": {
              "current_db": 25.5,
              "predicted_db": 23.2,
              "confidence": 0.85
            },
            "queue_utilization": {
              "current_utilization": 0.65,
              "predicted_utilization": 0.74,
              "confidence": 0.82
            }
          }
        },
        {
          "horizon_minutes": 5,
          "predictions": {
            "snr_degradation": {
              "current_db": 25.5,
              "predicted_db": 21.5,
              "confidence": 0.78
            },
            "queue_utilization": {
              "current_utilization": 0.65,
              "predicted_utilization": 0.82,
              "confidence": 0.75
            }
          }
        }
      ]
    }
  ]
}

Response Fields

Name	Type	Description
node_id	string	The queried node
timestamp	string	Prediction generation time
cached	boolean	Whether result was from cache
links	array	Predictions for each connected link

Link Prediction Fields

Name	Type	Description
src	string	Source node ID
dst	string	Destination node ID
horizons	array	Predictions at different time horizons

Horizon Fields

Name	Type	Description
horizon_minutes	number	Forecast horizon (1, 3, or 5 minutes)
predictions	object	SNR and utilization predictions

SNR Degradation Prediction

Name	Type	Description
current_db	number	Current SNR in dB
predicted_db	number	Predicted SNR in dB
confidence	number	Model confidence (0-1)

Queue Utilization Prediction

Name	Type	Description
current_utilization	number	Current queue utilization (0-1)
predicted_utilization	number	Predicted utilization (0-1)
confidence	number	Model confidence (0-1)

Prediction Models

SNR Degradation Model

LSTM-based model predicting signal quality drops.

Input Features:

• Elevation angle (degrees)
• Rain rate (mm/hr)
• Rain attenuation (dB)
• Traffic (Gbps)
• Utilization

Training Data: 10-minute sliding windows of telemetry

Queue Utilization Model

LSTM-based model predicting buffer congestion.

Input Features:

• Current queue utilization
• Total inbound traffic (Gbps)
• Backhaul capacity (Gbps)
• Net flow rate (Gbps)
• Backhaul type (microwave flag)

Caching

Predictions are cached in Redis with a 60-second TTL.

To bypass cache:

curl "https://api.constellation-io.com/api/v1/predictions/sat-001?use_cache=false"

Error Responses

Node Not Found (404)

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Node sat-999 not found or has no associated links"
  }
}

Service Unavailable (503)

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Graph engine not initialized"
  }
}

CLI Example

constellation predictions get sat-001

Output:

Predictions for sat-001 (generated 2026-01-16T20:00:00Z)

Link: sat-001 → gs-001
┌─────────┬─────────────────────┬─────────────────────┐
│ Horizon │ SNR Degradation     │ Queue Utilization   │
├─────────┼─────────────────────┼─────────────────────┤
│ 1 min   │ 25.5 → 24.8 dB (92%)│ 0.65 → 0.68 (89%)  │
│ 3 min   │ 25.5 → 23.2 dB (85%)│ 0.65 → 0.74 (82%)  │
│ 5 min   │ 25.5 → 21.5 dB (78%)│ 0.65 → 0.82 (75%)  │
└─────────┴─────────────────────┴─────────────────────┘

Python Example

import requests

response = requests.get(
    "https://api.constellation-io.com/api/v1/predictions/sat-001",
    headers={"Authorization": f"Bearer {token}"},
)

predictions = response.json()

for link in predictions["links"]:
    print(f"Link: {link['src']} → {link['dst']}")
    for horizon in link["horizons"]:
        snr = horizon["predictions"]["snr_degradation"]
        util = horizon["predictions"]["queue_utilization"]
        print(f"  {horizon['horizon_minutes']}min: SNR {snr['current_db']:.1f} → {snr['predicted_db']:.1f} dB")
        print(f"         Util {util['current_utilization']:.2f} → {util['predicted_utilization']:.2f}")

Use Cases

1. Proactive Rerouting

When predicted SNR drops below threshold, preemptively reroute traffic:

for link in predictions["links"]:
    snr_5min = link["horizons"][2]["predictions"]["snr_degradation"]
    if snr_5min["predicted_db"] < 15.0 and snr_5min["confidence"] > 0.7:
        initiate_reroute(link["src"], link["dst"])

2. Load Balancing

Balance traffic based on predicted utilization:

for link in predictions["links"]:
    util_3min = link["horizons"][1]["predictions"]["queue_utilization"]
    if util_3min["predicted_utilization"] > 0.85:
        reduce_traffic(link["src"], link["dst"], factor=0.5)

3. Alerting

Generate alerts for predicted degradations:

for link in predictions["links"]:
    snr_1min = link["horizons"][0]["predictions"]["snr_degradation"]
    degradation = snr_1min["current_db"] - snr_1min["predicted_db"]
    if degradation > 5.0:
        send_alert(f"SNR degradation predicted: {degradation:.1f} dB in 1 minute")