Skip to main content

​
Simulation Sessions

Version: 1.1.0 Simulation Sessions extend the Orbital Sim with stateful, multi-satellite simulation. Unlike the stateless propagation endpoints, sessions persist constellation state in KV and let you advance time step-by-step, track subsystem health, model inter-satellite link quality, and inject faults.
Sessions are designed for integration testing of constellation workloads. They power the agent executor’s simulated satellite mode and the CAE constellation planner’s test harness.

​
Base URL

https://sim.rotastellar.com

​
Concepts

​
Session Lifecycle

A session represents a constellation of up to 50 satellites. On creation, each satellite is initialized with orbital elements and default subsystem state. You advance the simulation by calling the tick endpoint, which propagates orbits, updates subsystems, checks for natural faults, and recalculates ISL links. Sessions are stored in the SIM_STATE KV binding with a 1-hour TTL. If a session is not ticked within one hour, it is automatically evicted.

​
Subsystem State

Every satellite in a session tracks five subsystems:
SubsystemUnitInitial ValueModel
battery%100Charge in sunlight, discharge in eclipse. Rate depends on compute load.
solar_powerW100 (sunlit) / 0 (eclipse)Binary based on eclipse state.
temperatureC20Rises under compute load, radiative cooling in eclipse.
memoryMB0 (of 512)Accumulates with data generation, freed on downlink.
cpu%0Set by active workload. Idle satellites report 0%.
Inter-satellite links (ISLs) are modeled between all satellite pairs within range:
ParameterValue
Max range5,000 km
Distance factor1 - (distance / 5000) * 0.6
Eclipse penalty0.9 (applied when either endpoint is in eclipse)
Effective bandwidth100 Mbps * quality
A link quality of 0 means the satellites are out of range. Quality degrades linearly with distance and is further penalized during eclipse due to thermal effects on transponders.

​
Natural Fault Detection

Each tick evaluates three natural fault conditions:
FaultConditionProbability
SAA radiation upsetSatellite passes through the South Atlantic Anomaly region2% per tick in region
Thermal exceedanceTemperature exceeds 50CDeterministic
Power criticalBattery drops below 5%Deterministic
When a natural fault triggers, it is included in the tick response as a faults array entry.

​
Endpoints

​
Create Session

POST /v1/sessions
Creates a new simulation session with the specified satellites. Request body:
FieldTypeRequiredDescription
satellitesarrayyesArray of satellite definitions (max 50)
satellites[].idstringyesUnique satellite identifier within the session
satellites[].elementsobjectyesOrbital elements (same schema as /v1/state)
curl -X POST https://sim.rotastellar.com/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "satellites": [
      {
        "id": "sat-1",
        "elements": {
          "altitude_km": 550,
          "inclination_deg": 53,
          "raan_deg": 0,
          "mean_anomaly_deg": 0
        }
      },
      {
        "id": "sat-2",
        "elements": {
          "altitude_km": 550,
          "inclination_deg": 53,
          "raan_deg": 0,
          "mean_anomaly_deg": 120
        }
      },
      {
        "id": "sat-3",
        "elements": {
          "altitude_km": 550,
          "inclination_deg": 53,
          "raan_deg": 0,
          "mean_anomaly_deg": 240
        }
      }
    ]
  }'
Response (201): 
{
  "session_id": "ses-a1b2c3d4",
  "satellite_count": 3,
  "created_at": "2026-03-10T12:00:00Z",
  "ttl_seconds": 3600
}
Sessions are limited to 50 satellites. Requests exceeding this limit return a 400 error.

​
Get Session State

GET /v1/sessions/:id
Returns the full constellation state including all satellite positions, subsystems, and active ISL links. Response (200): 
{
  "session_id": "ses-a1b2c3d4",
  "tick": 5,
  "sim_time": "2026-03-10T12:25:00Z",
  "satellites": [
    {
      "id": "sat-1",
      "position": {
        "lat": 42.15,
        "lon": -73.82,
        "altitude_km": 550.3
      },
      "in_eclipse": false,
      "subsystems": {
        "battery": 94.2,
        "solar_power": 100,
        "temperature": 22.5,
        "memory": 45.0,
        "cpu": 30
      }
    }
  ],
  "isl_links": [
    {
      "from": "sat-1",
      "to": "sat-2",
      "distance_km": 1823.4,
      "quality": 0.78,
      "bandwidth_mbps": 78.0,
      "eclipse_penalty_applied": false
    }
  ]
}

​
Tick (Advance Simulation)

POST /v1/sessions/:id/tick
Advances the simulation by one time step. Each tick performs the following in order:
  1. Propagate all satellite orbits forward
  2. Detect eclipse transitions (sunlit/shadow)
  3. Update subsystem state (battery, thermal, solar)
  4. Check natural fault conditions
  5. Recalculate all ISL links
Request body:
FieldTypeRequiredDefaultDescription
duration_snumberno300Time step duration in seconds
curl -X POST https://sim.rotastellar.com/v1/sessions/ses-a1b2c3d4/tick \
  -H "Content-Type: application/json" \
  -d '{
    "duration_s": 300
  }'
Response (200): 
{
  "session_id": "ses-a1b2c3d4",
  "tick": 6,
  "sim_time": "2026-03-10T12:30:00Z",
  "duration_s": 300,
  "satellites": [ ... ],
  "isl_links": [ ... ],
  "eclipse_transitions": [
    {
      "satellite_id": "sat-2",
      "transition": "entered_eclipse",
      "sim_time": "2026-03-10T12:27:14Z"
    }
  ],
  "faults": []
}
The eclipse_transitions array only contains satellites whose eclipse state changed during this tick. An empty array means no transitions occurred.

​
Inject Fault

POST /v1/sessions/:id/fault
Injects a fault into a specific satellite. The fault takes effect immediately and is reflected in the session state. Request body:
FieldTypeRequiredDescription
satellite_idstringyesTarget satellite
fault_typestringyesOne of the fault types below
Fault types and effects:
Fault TypeImmediate Effect
power_lossBattery set to 0%, solar power disabled
thermal_exceedanceTemperature set to 85C
radiation_upsetCPU reset to 0%, memory corrupted (set to 0)
comms_failureAll ISL links to/from this satellite removed
isl_degradationAll ISL links to/from this satellite quality halved
curl -X POST https://sim.rotastellar.com/v1/sessions/ses-a1b2c3d4/fault \
  -H "Content-Type: application/json" \
  -d '{
    "satellite_id": "sat-2",
    "fault_type": "power_loss"
  }'
Response (200): 
{
  "session_id": "ses-a1b2c3d4",
  "satellite_id": "sat-2",
  "fault_type": "power_loss",
  "applied_at_tick": 6,
  "effects": {
    "battery": 0,
    "solar_power": 0
  }
}
Fault injection is irreversible within a session. To restore a satellite, create a new session.

​
Storage

Sessions are stored in the SIM_STATE KV binding. Each session is a single JSON document keyed by session:{session_id}. The 1-hour TTL ensures stale sessions are automatically cleaned up.
KV BindingKey PatternTTL
SIM_STATEsession:{session_id}3600s (1 hour)

Orbital Sim Overview

Stateless propagation, eclipse detection, and pass prediction

Sim API Reference

Full API reference for all Sim endpoints