Docs › Sky today: retrogrades, Moon phase, next events

Sky today: retrogrades, Moon phase, next events

The sky today (no location needed): planet positions, retrogrades and Moon phase now, plus the exact UTC times of the next ingresses, stations (Mercury retrograde), new and full moons and aspects.

POST https://astro-agent.dev/v1/western/sky · $0.01 per call · MCP tool sky_today · Try it in the playground

For agents and apps that follow the sky itself (calendars, daily content, alerts): positions with retrograde flags and the Moon's phase and illumination at a moment (default: now, UTC), then every sign ingress, retrograde/direct station, lunation (new, quarter, full) and major aspect between the planets over the next 1-90 days, each to the minute. Tropical or sidereal. Pass 'datetime' for a reproducible call.

Authentication

Send your key in the X-Credits-Token header. A free key comes with the Free plan (10,000 calls a month on the core routes, 100 a month on the premium data routes). Without a key, each client gets 1 free call on the $0.01-0.02 routes; past it the API answers 402 with an x402 / MPP pay-per-call offer.

Parameters

ParameterTypeRequiredDefaultDescription
datetimestringLocal civil date-time, ISO 8601: '1990-05-15T14:30' (local clock time at the place) or with an explicit offset '1990-05-15T14:30:00+02:00'. Alternative: 'date' + 'time'.
datestringYYYY-MM-DD (use with 'time' instead of 'datetime').
timestringHH:MM or HH:MM:SS, 24 h. Omit if unknown (computed at 12:00 with a TIME_UNKNOWN warning).
latitudenumberDecimal degrees, north positive.
longitudenumberDecimal degrees, east positive.
timezonestringIANA zone, e.g. 'Asia/Kolkata'. Optional: resolved from the coordinates, with the historical offset (DST, Local Mean Time) of that date.
time_basisstring: civil | utc | lmt | true_solar"civil"What the given clock time is: civil wall-clock (default), UTC, Local Mean Time, or true (apparent) solar time.
ambiguous_timestring: earlier | later"earlier"Which occurrence to use when a local time happens twice (DST fall-back).
daysinteger30How many days ahead to list events. Example: 30.
optionsobjectOptional zodiac settings.
options.zodiacstring: tropical | sidereal"tropical"'tropical' (default) or 'sidereal' (pair it with 'ayanamsa').
options.ayanamsastring: fagan_bradley | krishnamurti | lahiri | raman | true_chitrapaksha | yukteshwar"lahiri"Only with zodiac=sidereal.

Example request

curl

curl -s https://astro-agent.dev/v1/western/sky \
  -H "X-Credits-Token: $ASTRO_AGENTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"datetime": "2026-10-01T00:00Z", "days": 30}'

Python

import os
import requests

body = {'datetime': '2026-10-01T00:00Z', 'days': 30}
r = requests.post("https://astro-agent.dev/v1/western/sky", json=body,
                  headers={"X-Credits-Token": os.environ.get("ASTRO_AGENTS_KEY", "")}, timeout=60)
if not r.ok:
    raise SystemExit(f"{r.status_code}: {r.text}")
data = r.json()

moon = data["result"]["now"]["moon"]
print("Moon:", moon["phase"], f'{moon["illumination"]:.0%} lit')
for ev in data["result"]["events"]:
    what = ev.get("kind") or ev.get("body") or ev.get("phase") or "-".join(ev.get("bodies", []))
    detail = ev.get("eclipse_type") or ev.get("turns") or ev.get("aspect") or ""
    print(ev["exact_utc"], ev["type"], what, detail)
print("result_sha256:", data["meta"]["result_sha256"])

JavaScript (Node 18+)

// Node 18+ (built-in fetch). Save as call.mjs and run: node call.mjs
const body = {"datetime": "2026-10-01T00:00Z", "days": 30};
const res = await fetch("https://astro-agent.dev/v1/western/sky", {
  method: "POST",
  headers: {"X-Credits-Token": process.env.ASTRO_AGENTS_KEY ?? "", "Content-Type": "application/json"},
  body: JSON.stringify(body),
});
if (!res.ok) throw new Error(`${res.status}: ${await res.text()}`);
const data = await res.json();

const moon = data.result.now.moon;
console.log("Moon:", moon.phase, Math.round(moon.illumination * 100) + "% lit");
for (const ev of data.result.events) {
  const what = ev.kind || ev.body || ev.phase || (ev.bodies || []).join("-");
  console.log(ev.exact_utc, ev.type, what, ev.eclipse_type || ev.turns || ev.aspect || "");
}
console.log("result_sha256:", data.meta.result_sha256);

Example response

A real response to the request above (lists shortened to 3 items). The same request always returns this result_sha256:

cf99aadfd6dd956e77a18036c26889937318593804e6010db4ab4d53b7c252b1

{
  "endpoint": "western/sky",
  "result": {
    "subject": {
      "time": {
        "local_input": "2026-10-01T00:00Z",
        "time_basis": "civil",
        "timezone": null,
        "timezone_source": "offset_in_datetime",
        "utc_offset": "+00:00",
        "is_dst": null,
        "utc": "2026-10-01T00:00:00Z",
        "julian_day_ut": 2461314.500001,
        "julian_day_tt": 2461314.500801,
        "delta_t_seconds": 69.091,
        "time_known": true
      }
    },
    "settings": {
      "zodiac": "tropical",
      "days": 30,
      "event_bodies": [
        "sun",
        "mercury",
        "venus"
      ],
      "aspects": {
        "conjunction": 0.0,
        "opposition": 180.0,
        "trine": 120.0,
        "square": 90.0,
        "sextile": 60.0
      },
      "precision": "event times +/- 1 minute (UTC); sidereal ingresses of slow planets +/- a few minutes (ayanamsa interpolated across the window)"
    },
    "now": {
      "points": [
        {
          "point": "sun",
          "name": "Sun",
          "longitude": 187.838755,
          "sign": "Libra",
          "sign_index": 6,
          "degree_in_sign": 7.838755,
          "position": "7°50'20\" Libra",
          "element": "air",
          "modality": "cardinal",
          "latitude": 0.000189,
          "speed_longitude": 0.982609,
          "retrograde": false,
          "distance_au": 1.001326
        },
        {
          "point": "moon",
          "name": "Moon",
          "longitude": 63.906575,
          "sign": "Gemini",
          "sign_index": 2,
          "degree_in_sign": 3.906575,
          "position": "3°54'24\" Gemini",
          "element": "air",
          "modality": "mutable",
          "latitude": 5.149558,
          "speed_longitude": 14.282884,
          "retrograde": false,
          "distance_au": 0.00247
        },
        {
          "point": "mercury",
          "name": "Mercury",
          "longitude": 210.679372,
          "sign": "Scorpio",
          "sign_index": 7,
          "degree_in_sign": 0.679372,
          "position": "0°40'46\" Scorpio",
          "element": "water",
          "modality": "fixed",
          "latitude": -1.747686,
          "speed_longitude": 1.324494,
          "retrograde": false,
          "distance_au": 1.175837
        }
      ],
      "retrograde": [
        "saturn",
        "uranus",
        "neptune"
      ],
      "moon": {
        "elongation_deg": 236.06782,
        "phase": "waning gibbous",
        "illumination": 0.77887,
        "waxing": false
      }
    },
    "events": [
      {
        "type": "aspect",
        "bodies": [
          "mercury",
          "mars"
        ],
        "aspect": "square",
        "exact_utc": "2026-10-02T09:14Z"
      },
      {
        "type": "aspect",
        "bodies": [
          "mercury",
          "pluto"
        ],
        "aspect": "square",
        "exact_utc": "2026-10-02T20:43Z"
      },
      {
        "type": "aspect",
        "bodies": [
          "mars",
          "neptune"
        ],
        "aspect": "trine",
        "exact_utc": "2026-10-02T22:18Z"
      }
    ],
    "counts": {
      "ingress": 2,
      "station": 3,
      "lunation": 4,
      "aspect": 14
    }
  },
  "meta": {
    "engine": "astro-agents/1.9.0",
    "ephemeris": "NASA/JPL DE440 (1800-01-01..2200-01-01)",
    "astronomy_library": "skyfield/1.55",
    "frame": "geocentric apparent positions, true ecliptic and equinox of date (IAU 2006/2000A)",
    "deterministic": true,
    "llm_used": false,
    "input_sha256": "04f06a1a5253ed754226a1d31ca7aa7b6ae017f859895f93c6dfd7e9fa865df8",
    "result_sha256": "cf99aadfd6dd956e77a18036c26889937318593804e6010db4ab4d53b7c252b1",
    "reproducibility": "result_sha256 = SHA-256 of the result serialized as JSON with sorted keys, no whitespace, UTF-8, floats rounded to 6 decimals. Same input + same engine version => same hash."
  }
}

Response fields

FieldTypeDescription
result.subjectobjectThe resolved input: 'time' (local input, time zone and historical UTC offset, UT, Julian days, Delta T) and, when given, 'location' (latitude, longitude).
result.settingsobjectSettings applied: zodiac (and ayanamsa), days ahead, the bodies and aspects searched, and the precision of event times.
result.nowobjectThe sky at the moment: 'points' (positions, signs, speeds, retrograde flags), 'retrograde' (bodies retrograde now) and 'moon' (elongation, phase name, illumination, waxing).
result.eventsarrayUpcoming events in time order, each with 'type' (ingress, station, lunation, aspect), its details and 'exact_utc'.
result.countsobjectNumber of events of each type.
result.warningsarrayNotes on the input or the calculation (for example an assumed local noon when only a date is given). Present only when there is something to say.
endpointstringThe route that computed it.
meta.input_sha256stringSHA-256 of the canonical request.
meta.result_sha256stringSHA-256 of the canonical result: POST /v1/verify recomputes it.
meta.engine_version / meta.ephemerisstringEngine release and ephemeris (NASA/JPL DE440).

Errors

400 for an invalid input (never charged), 401 / 403 for a key problem, 402 to pay, 429 for a quota or rate limit: see the error reference.