Skip to content
Occult API
POST/api/astro/retrograde/1 credit

Retrograde periods

Every retrograde period for a year, in one small response. Retrograde, or vakri, motion is the apparent backwards drift of a planet against the stars, and astrological practice treats those spans as a distinct phase in the planet's behaviour. Send `year` and nothing else. The response is `data.planets`, an object keyed by planet name, each holding a list of `{start, end}` timestamps in UTC. Periods running across a year boundary are clipped to 1 January and 31 December, so a window beginning at `01-01 00:00:00` actually started in the previous year. A planet that never turns retrograde in that year gets an empty list. Ten keys are returned: mercury, venus, mars, jupiter, saturn, uranus, neptune, pluto, rahu and ketu. The Sun and Moon are omitted because they are never retrograde as seen from Earth. Rahu and Ketu are derived from the mean lunar node, which drifts steadily backwards all year with no station, so both always show a single window covering the whole year; using the true node instead would produce dozens of spurious few-day entries. Station times are found by bracketing the day on which longitudinal speed changes sign and then narrowing within it, so they are precise to well under a minute. The same figures appear inside `/api/planetary_details/` bundled with eight other calculations; this endpoint returns the retrograde data alone.

https://yogataraapi.prahlad.app/api/astro/retrograde/
Test Request

Authentication

Send your key in the X-API-Key header. Keys are server-side credentials — never put one in browser JavaScript or a mobile app.

X-API-Key: yt_live_a1b2c3d4_…
Content-Type: application/json

Request fields

FieldTypeRequiredNotes
yearintegerrequired

Year of birth as a number, e.g. 1990. Four digits.

min 1800 · max 2400

Example request

curl -X POST https://yogataraapi.prahlad.app/api/astro/retrograde/ \
  -H "X-API-Key: $OCCULT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"year":2026}'

Response

{
  "data": {
    "year": 2026,
    "planets": {
      "mercury": [
        {
          "start": "2026-02-26 06:47:34",
          "end": "2026-03-20 19:33:02"
        },
        {
          "start": "2026-06-29 17:34:35",
          "end": "2026-07-23 22:58:49"
        },
        {
          "start": "2026-10-24 07:12:44",
          "end": "2026-11-13 15:54:27"
        }
      ],
      "venus": [
        {
          "start": "2026-10-03 07:13:14",
          "end": "2026-11-14 00:29:50"
        }
      ],
      "mars": [],
      "jupiter": [
        {
          "start": "2026-01-01 00:00:00",
          "end": "2026-03-11 03:53:41"
        },
        {
          "start": "2026-12-13 00:30:39",
          "end": "2026-12-31 00:00:00"
        }
      ],
      "saturn": [
        {
          "start": "2026-07-26 18:57:26",
          "end": "2026-12-11 00:30:23"
        }
      ],
      "uranus": [
        {
          "start": "2026-01-01 00:00:00",
          "end": "2026-02-04 02:56:33"
        },
        {
          "start": "2026-09-10 18:24:34",
          "end": "2026-12-31 00:00:00"
        }
      ],
      "neptune": [
        {
          "start": "2026-07-07 09:57:49",
          "end": "2026-12-13 00:46:51"
        }
      ],
      "pluto": [
        {
          "start": "2026-05-06 12:13:55",
          "end": "2026-10-16 05:33:46"
        }
      ],
      "rahu": [
        {
          "start": "2026-01-01 00:00:00",
          "end": "2026-12-31 00:00:00"
        }
      ],
      "ketu": [
        {
          "start": "2026-01-01 00:00:00",
          "end": "2026-12-31 00:00:00"
        }
      ]
    }
  },
  "message": "successful",
  "is_error": false
}

Captured from a real call using the exact request above. Results sit under data.

Errors

Metering errors return { "error": "…", "message": "<code>", "is_error": true }. Show error to people and branch on message. See the error reference.