---
title: "Check planet retrograde status"
method: POST
path: "/ephemeris/retrograde-status"
tags: ["ephemeris"]
---

# Check planet retrograde status

`POST /ephemeris/retrograde-status`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/ephemeris/retrograde-status`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-OpenEphemeris-API-Key`
  - API key in header `X-API-Key`
  - API key in header `X-Service-Key`

Lightweight endpoint for determining whether a planet is retrograde at a specific time. Returns motion type (direct/retrograde/stationary) and speed data.

## Query parameters

- `output_mode` string, nullable
- `format` string

## Headers

- `authorization` string, nullable
- `X-API-Key` string, nullable
- `X-OpenEphemeris-API-Key` string, nullable
- `apikey` string, nullable

## Request body

- RetrogradeStatusRequest: Request for planet retrograde status check.
  - `date_time` DateTimeInput, required: Date/time input in ISO-8601, component, or Julian day form. A value that states a clock time must also state its zone, either as a suffix on the string or via the `timezone` field below.
    - `components` object: Date/time components (year, month, day, and optionally hour, minute, second). If hour/minute are present, pass `timezone` alongside them; without it the request is rejected with 400 ambiguous_datetime. Omit the clock entirely and the date resolves to 12:00 UTC.
    - `iso` string: ISO-8601 datetime (supported range 1550–2650 CE, JPL DE440). If it states a clock time it must carry its zone: either a 'Z'/±HH:MM suffix on the string ("1987-07-15T09:01:00-05:00"), or a `timezone` passed alongside it. A zone-less clock time is rejected with 400 ambiguous_datetime — it is not read as UTC. A date-only value ("1987-07-15") has no clock to be ambiguous about and resolves to 12:00 UTC.
    - `julian_day` number, double: Julian Day Number (always UTC-based, so it needs no zone)
    - `timezone` TimezoneInput: Timezone input using IANA names or UTC offsets.
      - `fold_preference` 'earlier' | 'later': Which occurrence to use when the naive local datetime falls in a fall-back fold (a repeated hour): 'earlier' (default — first occurrence) or 'later'. Only meaningful for naive datetimes; the response reports datetime_status=ambiguous_fold either way so the ambiguity can be surfaced to the user.
      - `iana_name` string: IANA timezone name
      - `time_standard` 'auto' | 'standard' | 'daylight': How to interpret a naive local datetime when this zone is applied. 'auto' (default): resolve through the historical-correction overlay where one covers the region/era, then IANA tzdata. 'standard': force the zone's standard (non-daylight) offset — for callers who KNOW the recorded time was standard time regardless of what tzdata believes. 'daylight': force standard+1h. Forcing either marks the resolution tz_confidence=client_override. Ignored when the datetime carries its own Z/±HH:MM suffix or when utc_offset is used.
      - `utc_offset` number: UTC offset in hours
  - `planet_id` integer, required: SE-compatible planet ID (0=Sun, 1=Moon, 2=Mercury, 3=Venus, 4=Mars, 5=Jupiter, 6=Saturn, 7=Uranus, 8=Neptune, 9=Pluto, 12=Mean Lilith, 13=Osculating Lilith, 40=Interpolated Lilith, 15=Chiron, 16=Pholus, 17-20=Ceres/Pallas/Juno/Vesta). Lunar nodes: id 10 (`north_node_mean`, named "North Node (Mean)") is the classical mean node (the IERS/Meeus mean-node polynomial, Swiss Ephemeris SE_MEAN_NODE): smooth and always retrograde. Id 11 (`north_node_true`, named "North Node (True)") is the osculating true node in the true ecliptic of date, computed from DE440 Moon state vectors (SE_TRUE_NODE) — the node Human Design software uses and the one /human-design/chart derives gates from: expect a +/-1.7 deg oscillation about the mean node, a variable longitude_speed, and occasional direct motion. Until 2026-09-26 id 10 served the true node (OE-BUG-2026-017). South Node has no id: add 180 deg to either node.

## Response `200`

Retrograde status determined successfully

- RetrogradeStatusResponse: Response from retrograde status check.
  - `is_retrograde` boolean, required: True if planet is in retrograde motion
  - `longitude_speed` number, required: Longitude speed in degrees per day
  - `motion_type` string, required: Motion classification: direct, retrograde, or stationary
  - `planet_id` integer, required: SE-compatible planet ID
  - `planet_name` string, required: Planet name
  - `speed_threshold` number: Threshold for stationary classification (degrees/day)
  - `success` boolean: Calculation success status

## Other responses

- `400`: Invalid input (e.g., unknown planet_id)
- `422`: Validation Error
- `500`: Calculation error

---

[API](https://skmtc.dev/openephemeris/apis/open-ephemeris-api.md) · [All operations](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/revisions/d195a769cb89?raw)