---
title: "Search a bounded interval for planetary ingresses, stations and exact major aspects"
method: POST
path: "/api/astro/planetary-events"
tags: ["Calculations"]
---

# Search a bounded interval for planetary ingresses, stations and exact major aspects

`POST /api/astro/planetary-events`

## Request

- Base URL: `https://api.cosmicephemeris.com`
- URL: `https://api.cosmicephemeris.com/api/astro/planetary-events`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Returns only physical apparent-geocentric longitude events: selected-zodiac sign-boundary crossings, tropical-longitude motion reversals and exact major-aspect longitude crossings. No aspect orbs, tangential contacts, houses, interpretations, eclipse claims, arbitrary targets, user kernels or search tuning. UTC dates 1800–2200; whole-second start-inclusive/end-exclusive intervals span at most 31 days. One-second timestamps and a 0.05-second numerical root tolerance are not physical accuracy guarantees. Independent Swiss Ephemeris/Moshier fixtures cover representative 2026 ingresses, stations and an exact aspect within 30 seconds; broader epoch acceptance remains separate. Each admitted request reserves one standard monthly quota unit before route validation or engine work, including failures and timeouts; failed or timed-out admitted attempts are not refunded. All plans; do not automatically retry. Source availability does not establish deployment.
Historical mode uses an explicit BCE/CE date object and UT1 conventions. Its response is the versioned historical envelope, not the modern UTC envelope. Read result for calculation fields and metadata for limits and uncertainty.

## Request body

- union
  - PlanetaryEventsRequest: Whole-second UTC, start-inclusive/end-exclusive interval greater than zero and at most 31 elapsed days. Both endpoints must fit UTC 1800-01-01T00:00:00Z through 2201-01-01T00:00:00Z, where the latter is an exclusive end only. Arrays use exact, unique enum values. Aspects defaults to all five major aspects when aspect is selected; aspects is forbidden otherwise, and aspect searches require at least two bodies.
    - `start_utc` string, date-time, required
    - `end_utc` string, date-time, required
    - `event_types` PlanetaryEventType[], required
    - `bodies` PlanetaryEventBody[], required
    - `aspects` PlanetaryEventAspect[]
    - `zodiac` string, nullable: tropical or sidereal; server trims whitespace and ignores case. Omitted/null selects tropical.
    - `ayanamsa` string, nullable: Sidereal supports lahiri, raman, krishnamurti, fagan_bradley, yukteshwar, sassanian, true_chitra, true_revati, true_pushya, galactic_center_0_sagittarius, galactic_alignment_mardyks, with case/whitespace normalization; other names return 400 in sidereal mode. Omitted/null selects lahiri. Tropical mode ignores a nonempty string and outputs null. This schema describes that compatibility behavior rather than claiming every string is a supported sidereal model.
  - HistoricalPlanetaryEventsRequest: Explicit historical mode, 1000 BCE (BC)–2500 CE (AD). No year zero, implicit calendar, UTC or IANA zone. Preserve tool-specific mathematical, geographic and search limits; calendar/time conventions and estimated Delta-T are not certified historical accuracy.
    - `event_types` PlanetaryEventType[], required
    - `bodies` PlanetaryEventBody[], required
    - `aspects` PlanetaryEventAspect[]
    - `zodiac` string, nullable: tropical or sidereal; server trims whitespace and ignores case. Omitted/null selects tropical.
    - `ayanamsa` string, nullable: Sidereal supports lahiri, raman, krishnamurti, fagan_bradley, yukteshwar, sassanian, true_chitra, true_revati, true_pushya, galactic_center_0_sagittarius, galactic_alignment_mardyks, with case/whitespace normalization; other names return 400 in sidereal mode. Omitted/null selects lahiri. Tropical mode ignores a nonempty string and outputs null. This schema describes that compatibility behavior rather than claiming every string is a supported sidereal model.
    - `start` HistoricalDateTime, required: Shared historical input contract; parsing alone does not enable a calculation route. Derived calculation records can include fractional seconds and are not this input type.
      - `date` HistoricalDate, required: Explicit civil date, 1000 BCE (BC)–2500 CE (AD); no year zero. Calendar validity is checked by the server. Available only on documented connected historical operations, with explicit UT1/fixed-offset conventions.
        - `year` integer, required
        - `era` 'BCE' | 'CE', required: Display BCE (BC) / CE (AD); API values remain BCE / CE. No year zero.
        - `month` integer, required
        - `day` integer, required
        - `calendar` 'proleptic_gregorian' | 'proleptic_julian', required: Explicit choice; applies the selected calendar rules throughout history without a regional adoption switch.
      - `time` string, required: Explicit HH:MM[:SS]; whole seconds only, no leap seconds. Normalized helper output includes seconds.
      - `timezone` string, required: Explicit UT1 or fixed offset UT1+/-HH:MM[:SS], within 14 hours. Local clock minus offset yields UT1, not UTC. No IANA timezone inference. Original offset spelling is preserved.
    - `end` HistoricalDateTime, required: Shared historical input contract; parsing alone does not enable a calculation route. Derived calculation records can include fractional seconds and are not this input type.
      - `date` HistoricalDate, required: Explicit civil date, 1000 BCE (BC)–2500 CE (AD); no year zero. Calendar validity is checked by the server. Available only on documented connected historical operations, with explicit UT1/fixed-offset conventions.
        - `year` integer, required
        - `era` 'BCE' | 'CE', required: Display BCE (BC) / CE (AD); API values remain BCE / CE. No year zero.
        - `month` integer, required
        - `day` integer, required
        - `calendar` 'proleptic_gregorian' | 'proleptic_julian', required: Explicit choice; applies the selected calendar rules throughout history without a regional adoption switch.
      - `time` string, required: Explicit HH:MM[:SS]; whole seconds only, no leap seconds. Normalized helper output includes seconds.
      - `timezone` string, required: Explicit UT1 or fixed offset UT1+/-HH:MM[:SS], within 14 hours. Local clock minus offset yields UT1, not UTC. No IANA timezone inference. Original offset spelling is preserved.

## Response `200`

Bounded planetary-event result.

- union
  - PlanetaryEventsResponse
    - `type` 'planetary_events', required
    - `status` 'current', required
    - `result` PlanetaryEventsResult, required
      - `start_utc` string, date-time, required: Normalized UTC timestamp; fractional seconds may be present.
      - `end_utc` string, date-time, required: Normalized UTC timestamp; fractional seconds may be present.
      - `events` PlanetaryEvent[], required
        - union
          - PlanetarySignIngressEvent
            - `type` 'sign_ingress', required
            - `utc` string, date-time, required: Normalized UTC timestamp; fractional seconds may be present.
            - `body` 'sun' | 'moon' | 'mercury' | 'venus' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune' | 'pluto', required
            - `direction` 'direct' | 'retrograde', required
            - `from_sign` 'aries' | 'taurus' | 'gemini' | 'cancer' | 'leo' | 'virgo' | 'libra' | 'scorpio' | 'sagittarius' | 'capricorn' | 'aquarius' | 'pisces', required
            - `to_sign` 'aries' | 'taurus' | 'gemini' | 'cancer' | 'leo' | 'virgo' | 'libra' | 'scorpio' | 'sagittarius' | 'capricorn' | 'aquarius' | 'pisces', required
            - `boundary_degrees` integer, required
            - `longitude_degrees` number, required
          - PlanetaryStationEvent
            - `type` 'station', required
            - `utc` string, date-time, required: Normalized UTC timestamp; fractional seconds may be present.
            - `body` 'sun' | 'moon' | 'mercury' | 'venus' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune' | 'pluto', required
            - `motion_after` 'direct' | 'retrograde', required
            - `longitude_degrees` number, required
          - PlanetaryExactAspectEvent
            - `type` 'aspect', required
            - `utc` string, date-time, required: Normalized UTC timestamp; fractional seconds may be present.
            - `body1` 'sun' | 'moon' | 'mercury' | 'venus' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune' | 'pluto', required
            - `body2` 'sun' | 'moon' | 'mercury' | 'venus' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune' | 'pluto', required
            - `aspect` 'conjunction' | 'sextile' | 'square' | 'trine' | 'opposition', required
            - `angle_degrees` 0 | 60 | 90 | 120 | 180, required
            - `body1_longitude_degrees` number, required
            - `body2_longitude_degrees` number, required
      - `event_count` integer, required
      - `model` 'de440-apparent-geocentric-planetary-events-v1', required
      - `interval` 'start_inclusive_end_exclusive', required
      - `timestamp_resolution_seconds` 1, required
    - `metadata` PlanetaryEventsMetadata, required
      - `ephemeris` 'JPL-DE440', required
      - `frame` 'apparent_geocentric_ecliptic_of_date', required
      - `zodiac` 'tropical' | 'sidereal', required
      - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks', nullable, required
      - `station_frame` 'tropical_longitude', required
      - `station_speed_definition` 'centered_one_hour_finite_difference', required
      - `aspect_policy` 'exact_longitude_crossings_only_no_orbs_no_tangencies', required
      - `timescale_data` 'bundled-skyfield', required
      - `search_step_hours` 6, required
      - `root_tolerance_seconds` 0.05, required
      - `interpretations` false, required
  - HistoricalPlanetaryEventsResponse
    - `schema` 'cosmicephemeris-historical-calculation-v1', required
    - `status` 'historical', required
    - `type` 'planetary-events', required
    - `input` HistoricalPlanetaryEventsRequest, required: Explicit historical mode, 1000 BCE (BC)–2500 CE (AD). No year zero, implicit calendar, UTC or IANA zone. Preserve tool-specific mathematical, geographic and search limits; calendar/time conventions and estimated Delta-T are not certified historical accuracy.
      - `event_types` PlanetaryEventType[], required
      - `bodies` PlanetaryEventBody[], required
      - `aspects` PlanetaryEventAspect[]
      - `zodiac` string, nullable: tropical or sidereal; server trims whitespace and ignores case. Omitted/null selects tropical.
      - `ayanamsa` string, nullable: Sidereal supports lahiri, raman, krishnamurti, fagan_bradley, yukteshwar, sassanian, true_chitra, true_revati, true_pushya, galactic_center_0_sagittarius, galactic_alignment_mardyks, with case/whitespace normalization; other names return 400 in sidereal mode. Omitted/null selects lahiri. Tropical mode ignores a nonempty string and outputs null. This schema describes that compatibility behavior rather than claiming every string is a supported sidereal model.
      - `start` HistoricalDateTime, required: Shared historical input contract; parsing alone does not enable a calculation route. Derived calculation records can include fractional seconds and are not this input type.
        - `date` HistoricalDate, required: Explicit civil date, 1000 BCE (BC)–2500 CE (AD); no year zero. Calendar validity is checked by the server. Available only on documented connected historical operations, with explicit UT1/fixed-offset conventions.
          - `year` integer, required
          - `era` 'BCE' | 'CE', required: Display BCE (BC) / CE (AD); API values remain BCE / CE. No year zero.
          - `month` integer, required
          - `day` integer, required
          - `calendar` 'proleptic_gregorian' | 'proleptic_julian', required: Explicit choice; applies the selected calendar rules throughout history without a regional adoption switch.
        - `time` string, required: Explicit HH:MM[:SS]; whole seconds only, no leap seconds. Normalized helper output includes seconds.
        - `timezone` string, required: Explicit UT1 or fixed offset UT1+/-HH:MM[:SS], within 14 hours. Local clock minus offset yields UT1, not UTC. No IANA timezone inference. Original offset spelling is preserved.
      - `end` HistoricalDateTime, required: Shared historical input contract; parsing alone does not enable a calculation route. Derived calculation records can include fractional seconds and are not this input type.
        - `date` HistoricalDate, required: Explicit civil date, 1000 BCE (BC)–2500 CE (AD); no year zero. Calendar validity is checked by the server. Available only on documented connected historical operations, with explicit UT1/fixed-offset conventions.
          - `year` integer, required
          - `era` 'BCE' | 'CE', required: Display BCE (BC) / CE (AD); API values remain BCE / CE. No year zero.
          - `month` integer, required
          - `day` integer, required
          - `calendar` 'proleptic_gregorian' | 'proleptic_julian', required: Explicit choice; applies the selected calendar rules throughout history without a regional adoption switch.
        - `time` string, required: Explicit HH:MM[:SS]; whole seconds only, no leap seconds. Normalized helper output includes seconds.
        - `timezone` string, required: Explicit UT1 or fixed offset UT1+/-HH:MM[:SS], within 14 hours. Local clock minus offset yields UT1, not UTC. No IANA timezone inference. Original offset spelling is preserved.
    - `result` object, required: Complete historical calculation adapter result. Times are explicit UT1 date records, never UTC strings; derived times may include fractional seconds and years outside the input range.
    - `metadata` object, required
      - `time_standard` 'UT1', required
      - `historical_accuracy_certified` unknown, required
      - `warnings` string[], required

## Other responses

- `400`: Invalid request, malformed JSON, out-of-range date/location, unknown model, invalid timezone or ambiguous/nonexistent clock-change time. Invalid attempts reaching quota reservation consume one unit.
- `401`: Missing, invalid, revoked API key or unavailable activated key owner. Dashboard cookies do not authenticate calculation routes.
- `403`: Origin not allowed by production CORS policy. Server-to-server requests can omit Origin.
- `404`: Wrong/case-variant/noncanonical or trailing-slash route; public paths have no version prefix.
- `413`: Request exceeds the body limit; gateway JSON is capped at 128 KiB. Edge failures may be HTML.
- `429`: Monthly quota exhausted, per-user two-request concurrency reached, or nginx rate/connection admission refused. Retry-After: 2 is sent for application per-user concurrency only, not a promise that monthly quota resets in two seconds.
- `500`: Bounded gateway/database/internal failure. An admitted attempt can still consume quota.
- `502`: Engine unavailable, unsuccessful internal server response or invalid upstream JSON. No engine internals are exposed.
- `503`: Four-request global calculation pool full (Retry-After: 2), maintenance or upstream service unavailable.
- `504`: Application engine timeout: 15 seconds normally; planetary events, house ingresses, aspect windows, event calendar, eclipse geometry, electional search, and event-rule search use 30 seconds; Nakshatra Timeline plus the explicitly enumerated readiness, robustness, location, uncertainty, and electional-audit family use 60 seconds. Timer includes response-body parsing; an admitted timeout consumes quota.

---

[API](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api.md) · [All operations](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cosmicephemeris/apis/cosmic-ephemeris-calculation-api/revisions/f041e924cea3?raw)