> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rotastellar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get State

> Compute satellite position, velocity, and eclipse status at a timestamp

<Note>
  **Base URL:** `https://sim.rotastellar.com`
  — No API key required.
</Note>

## Request

<ParamField body="elements" type="object" required>
  Orbital elements defining the satellite orbit. Must include either `altitude_km` or `mean_motion`, plus `inclination_deg`. See [Orbital Elements](/sim/overview#orbital-elements) for full schema.
</ParamField>

<ParamField body="timestamp" type="string">
  ISO 8601 timestamp for computation. Defaults to current time.
</ParamField>

<RequestExample>
  ```bash theme={null}
  curl -X POST https://sim.rotastellar.com/v1/state \
    -H "Content-Type: application/json" \
    -d '{
      "elements": {
        "altitude_km": 550,
        "inclination_deg": 53,
        "eccentricity": 0.0001,
        "raan_deg": 0,
        "mean_anomaly_deg": 0,
        "epoch": "2026-03-08T00:00:00Z"
      },
      "timestamp": "2026-03-08T12:00:00Z"
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://sim.rotastellar.com/v1/state",
      json={
          "elements": {
              "altitude_km": 550,
              "inclination_deg": 53
          }
      }
  )
  state = response.json()
  print(f"Position: {state['lat']:.2f}°, {state['lon']:.2f}°")
  print(f"Eclipse: {state['in_eclipse']}")
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "lat": 42.15,
    "lon": -73.82,
    "altitude_km": 550.3,
    "velocity_km_s": 7.59,
    "in_eclipse": false,
    "orbit_fraction": 0.234,
    "timestamp": "2026-03-08T12:00:00Z"
  }
  ```

  ```json 400 Invalid Elements theme={null}
  {
    "error": "invalid_elements",
    "message": "elements must include altitude_km or mean_motion, and inclination_deg"
  }
  ```
</ResponseExample>

## Response Fields

| Field            | Type    | Description                            |
| ---------------- | ------- | -------------------------------------- |
| `lat`            | number  | Geodetic latitude (degrees)            |
| `lon`            | number  | Geodetic longitude (degrees)           |
| `altitude_km`    | number  | Height above WGS-84 ellipsoid          |
| `velocity_km_s`  | number  | Orbital velocity                       |
| `in_eclipse`     | boolean | Whether satellite is in Earth's shadow |
| `orbit_fraction` | number  | Position in orbit (0–1)                |
| `timestamp`      | string  | ISO 8601 computation timestamp         |