---
title: "Calculate secondary-progressed planets with natal context"
method: POST
path: "/api/astro/secondary-progressions"
tags: ["Calculations"]
---

# Calculate secondary-progressed planets with natal context

`POST /api/astro/secondary-progressions`

## Request

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

Day-for-year secondary-progressed PLANETS only. Required target>=birth instant; all civil dates 1800–2200, times known, UTC defaults and DST rejection. Fixed365.2421904-day year in TT. Returned angles/houses are explicitly natal context, never progressed. No progressed angles, houses, aspects, nodes, speed or arbitrary year model. All admitted attempts use one standard quota unit, including free plans. No practitioner sign-off is claimed.

Each admitted request reserves one monthly usage unit before route validation or engine work; failed or timed-out admitted attempts are not refunded. Do not automatically retry.
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
  - SecondaryProgressionsRequest: Day-for-year secondary-progressed PLANETS only. Required target>=birth instant; all civil dates 1800–2200, times known, UTC defaults and DST rejection. Fixed365.2421904-day year in TT. Returned angles/houses are explicitly natal context, never progressed. No progressed angles, houses, aspects, nodes, speed or arbitrary year model.
    - `birth` CalculationBirthInput, required: Strict nested birth input; no unknown properties, nulls, booleans or numeric strings. Known civil time required; semantic date/DST/undefined-angle validation occurs on the server.
      - `date` string, date, required: Valid Gregorian YYYY-MM-DD local civil date, inclusive 1800-01-01 through 2200-12-31. Calendar validity and timezone conversion are checked by the server.
      - `time` string, required: HH:MM or HH:MM:SS; no offset in this field. Use timezone to select the civil-time zone.
      - `timezone` string: Valid IANA zone; UTC when omitted. Ambiguous and nonexistent civil times are rejected.
      - `lat` number, required
      - `lon` number, required
    - `target` CivilTimeInput, required
      - `date` string, date, required: Valid Gregorian YYYY-MM-DD local civil date, inclusive 1800-01-01 through 2200-12-31. Calendar validity and timezone conversion are checked by the server.
      - `time` string, required: HH:MM or HH:MM:SS; no offset in this field. Use timezone to select the civil-time zone.
      - `timezone` string
    - `zodiac` 'tropical' | 'sidereal'
    - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks'
    - `house_system` 'equal' | 'whole_sign'
  - HistoricalSecondaryProgressionsRequest: 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.
    - `birth` HistoricalBirthInput, required
      - `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.
      - `lat` number, required
      - `lon` number, required
    - `target` 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.
    - `zodiac` 'tropical' | 'sidereal'
    - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks'
    - `house_system` 'equal' | 'whole_sign'

## Response `200`

Successful calculation. Field nesting is specific to this route.

- union
  - SecondaryProgressionsResponse
    - `type` 'secondary_progressions', required
    - `status` 'current', required
    - `method` 'day_for_year', required
    - `input` object, required
      - `birth` CalculationMomentResult, required
        - `date` string, date, required: Valid Gregorian YYYY-MM-DD local civil date, inclusive 1800-01-01 through 2200-12-31. Calendar validity and timezone conversion are checked by the server.
        - `time` string, required: HH:MM or HH:MM:SS; no offset in this field. Use timezone to select the civil-time zone.
        - `timezone` string, required: Valid IANA zone; UTC when omitted. Ambiguous and nonexistent civil times are rejected.
        - `lat` number, required
        - `lon` number, required
      - `target` object, required
        - `date` string, date, required: Valid Gregorian YYYY-MM-DD local civil date, inclusive 1800-01-01 through 2200-12-31. Calendar validity and timezone conversion are checked by the server.
        - `time` string, required: HH:MM or HH:MM:SS; no offset in this field. Use timezone to select the civil-time zone.
        - `timezone` string, 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', required
      - `house_system` 'equal' | 'whole_sign', required
    - `birth_utc` string, date-time, required: Normalized UTC timestamp; fractional seconds may be present.
    - `target_utc` string, date-time, required: Normalized UTC timestamp; fractional seconds may be present.
    - `progressed_utc` string, required: Derived UTC instant with six fractional digits. Second 60 is preserved during an actual recorded leap second; JavaScript Date and Python datetime cannot directly parse that value. Use progressed_tt_jd for display/reference only; no single-JD round-trip was used in the calculation.
    - `timing` object, required
      - `year_days` 365.2421904, required
      - `elapsed_years` number, required
      - `progressed_days` number, required
      - `time_scale` 'TT', required
      - `progressed_tt_jd` number, 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', required
    - `progressed_planets` WesternPlanets, required
      - `Sun` WesternPoint, required
        - `lon` number, required
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required
      - `Moon` WesternPoint, required
        - `lon` number, required
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required
      - `Mercury` WesternPoint, required
        - `lon` number, required
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required
      - `Venus` WesternPoint, required
        - `lon` number, required
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required
      - `Mars` WesternPoint, required
        - `lon` number, required
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required
      - `Jupiter` WesternPoint, required
        - `lon` number, required
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required
      - `Saturn` WesternPoint, required
        - `lon` number, required
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required
      - `Uranus` WesternPoint, required
        - `lon` number, required
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required
      - `Neptune` WesternPoint, required
        - `lon` number, required
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required
      - `Pluto` WesternPoint, required
        - `lon` number, required
        - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
        - `deg_in_sign` number, required
    - `natal_context` object, required
      - `planets` WesternPlanets, required
        - `Sun` WesternPoint, required
          - `lon` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `deg_in_sign` number, required
        - `Moon` WesternPoint, required
          - `lon` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `deg_in_sign` number, required
        - `Mercury` WesternPoint, required
          - `lon` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `deg_in_sign` number, required
        - `Venus` WesternPoint, required
          - `lon` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `deg_in_sign` number, required
        - `Mars` WesternPoint, required
          - `lon` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `deg_in_sign` number, required
        - `Jupiter` WesternPoint, required
          - `lon` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `deg_in_sign` number, required
        - `Saturn` WesternPoint, required
          - `lon` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `deg_in_sign` number, required
        - `Uranus` WesternPoint, required
          - `lon` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `deg_in_sign` number, required
        - `Neptune` WesternPoint, required
          - `lon` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `deg_in_sign` number, required
        - `Pluto` WesternPoint, required
          - `lon` number, required
          - `sign` 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces', required
          - `deg_in_sign` number, required
      - `angles` WesternAngles, required
        - `ascendant` number, required
        - `mc` number, required
      - `houses` WesternHouses, required
        - `system` 'equal' | 'whole_sign', required
        - `cusps` object, required
          - `1` number, required
          - `2` number, required
          - `3` number, required
          - `4` number, required
          - `5` number, required
          - `6` number, required
          - `7` number, required
          - `8` number, required
          - `9` number, required
          - `10` number, required
          - `11` number, required
          - `12` number, required
    - `metadata` SecondaryProgressionsMetadata, required
      - `source_frame` 'apparent-geocentric-ecliptic-of-each-ephemeris-date', required
      - `position_precision` 'unrounded-binary64', required
      - `year_convention` 'fixed-365.2421904-days-not-calendar-birthdays', required
      - `time_policy` 'uniform-TT-elapsed-days-divided-by-year-days', required
      - `timescale_data` 'bundled-skyfield', required
      - `utc_output` 'leap-second-aware-ISO-8601', required
      - `progressed_angles` 'not-calculated', required
      - `progressed_houses` 'not-calculated', required
      - `angle_policy` 'fixed-natal-context-only', required
      - `location_policy` 'birth-location-for-natal-context-only', required
      - `sidereal_policy` 'per-ephemeris-date-ayanamsa' | 'not-applicable', required
      - `aspects` 'not-included', required
      - `nodes` 'not-included', required
      - `interpretations` false, required
      - `practitioner_review` 'not-completed', required
  - HistoricalSecondaryProgressionsResponse
    - `schema` 'cosmicephemeris-historical-calculation-v1', required
    - `status` 'historical', required
    - `type` 'secondary-progressions', required
    - `input` HistoricalSecondaryProgressionsRequest, 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.
      - `birth` HistoricalBirthInput, required
        - `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.
        - `lat` number, required
        - `lon` number, required
      - `target` 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.
      - `zodiac` 'tropical' | 'sidereal'
      - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks'
      - `house_system` 'equal' | 'whole_sign'
    - `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)