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
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
datetime | string | | Local 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'. | |
date | string | | YYYY-MM-DD (use with 'time' instead of 'datetime'). | |
time | string | | HH:MM or HH:MM:SS, 24 h. Omit if unknown (computed at 12:00 with a TIME_UNKNOWN warning). | |
latitude | number | | Decimal degrees, north positive. | |
longitude | number | | Decimal degrees, east positive. | |
timezone | string | | IANA zone, e.g. 'Asia/Kolkata'. Optional: resolved from the coordinates, with the historical offset (DST, Local Mean Time) of that date. | |
time_basis | string: 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_time | string: earlier | later | "earlier" | Which occurrence to use when a local time happens twice (DST fall-back). | |
days | integer | 30 | How many days ahead to list events. Example: 30. | |
options | object | | Optional zodiac settings. | |
options.zodiac | string: tropical | sidereal | "tropical" | 'tropical' (default) or 'sidereal' (pair it with 'ayanamsa'). | |
options.ayanamsa | string: 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
| Field | Type | Description |
|---|---|---|
result.subject | object | The resolved input: 'time' (local input, time zone and historical UTC offset, UT, Julian days, Delta T) and, when given, 'location' (latitude, longitude). |
result.settings | object | Settings applied: zodiac (and ayanamsa), days ahead, the bodies and aspects searched, and the precision of event times. |
result.now | object | The sky at the moment: 'points' (positions, signs, speeds, retrograde flags), 'retrograde' (bodies retrograde now) and 'moon' (elongation, phase name, illumination, waxing). |
result.events | array | Upcoming events in time order, each with 'type' (ingress, station, lunation, aspect), its details and 'exact_utc'. |
result.counts | object | Number of events of each type. |
result.warnings | array | Notes 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. |
endpoint | string | The route that computed it. |
meta.input_sha256 | string | SHA-256 of the canonical request. |
meta.result_sha256 | string | SHA-256 of the canonical result: POST /v1/verify recomputes it. |
meta.engine_version / meta.ephemeris | string | Engine 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.