---
title: "Calculate a natal Vimshottari cycle"
method: POST
path: "/api/astro/vimshottari"
tags: ["Calculations"]
---

# Calculate a natal Vimshottari cycle

`POST /api/astro/vimshottari`

## Request

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

Additive current calculation. Strict request shape; unknown fields, explicit nulls, noncanonical enums and numeric coordinate strings return 400. Exact poles and ambiguous/nonexistent civil times are rejected. Numerical checks are not practitioner sign-off. Sidereal-only with Lahiri default; retained-nutation frame and mean nodes. 

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.

Sidereal-only supported with fixed Julian years of 365.25 days and a 120-year cycle anchored at the theoretical start of the birth mahadasha. Omitted depth or explicit 2 returns the unchanged two-level response. Opt-in depth 3 adds 729 pratyantardashas; depth 4 adds 6,561 sookshma-dasha leaves. Both use exact proportional integer-microsecond durations and complete active-lord/count metadata. No arbitrary depth, date query, range or year model.
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
  - VimshottariRequest: Sidereal-only supported with fixed Julian years of 365.25 days and a 120-year cycle anchored at the theoretical start of the birth mahadasha. Omitted depth or explicit 2 returns the unchanged two-level response. Opt-in depth 3 adds 729 pratyantardashas; depth 4 adds 6,561 sookshma-dasha leaves. Both use exact proportional integer-microsecond durations and explicit active-lord/count metadata. No arbitrary depth, date query, range or 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
    - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks'
    - `depth` 2 | 3 | 4: Only 2, 3, or 4; no null, string or boolean. Explicit 2 is output-identical to omission.
  - HistoricalVimshottariRequest: 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
    - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks'
    - `depth` 2 | 3 | 4: Only 2, 3, or 4; no null, string or boolean. Explicit 2 is output-identical to omission.

## Response `200`

Successful calculation. Field nesting is specific to this route.

- union
  - VimshottariResponseDepth2: All period timestamps are UTC with microsecond resolution and half-open intervals. Derived period offsets may extend beyond the birth ephemeris window; this does not extrapolate ephemeris positions. Unrounded Moon determines nakshatra and birth balance; elapsed duration is floored to microseconds. Current without practitioner sign-off.
    - `status` 'current', required
    - `type` 'vimshottari', required
    - `input` object, required
      - `birth` NormalizedBirth, required: Synastry normalizes numeric coordinates, zodiac and ayanamsa. Supplied timezone is echoed (including null/empty string); omitted timezone is UTC.
        - `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, nullable, required: IANA timezone name (for example America/New_York). Omission, null, or empty string means UTC for a birth input. Nonexistent or ambiguous local clock-change times return 400; provide the known UTC date/time with timezone UTC instead.
        - `lat` number, required
        - `lon` 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
      - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks', required
    - `birth_utc` string, date-time, required: Normalized UTC timestamp; fractional seconds may be present.
    - `zodiac` 'sidereal', required
    - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks', required
    - `moon` object, required
      - `sidereal_longitude` number, required
      - `nakshatra` object, required
        - `index` integer, required
        - `name` string, required
        - `lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', required
        - `pada` integer, required
        - `fraction_elapsed` number, required
    - `birth_balance` object, required
      - `lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', required
      - `subperiod_lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', required
      - `elapsed_years` number, required
      - `remaining_years` number, required
      - `remaining_days` number, 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.
    - `cycle` object, required
      - `years` 120, 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.
    - `periods` DashaPeriod[], required
      - `lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', required
      - `years` 7 | 20 | 6 | 10 | 18 | 16 | 19 | 17, 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.
      - `active_at_birth` boolean, required
      - `subperiods` DashaSubperiod[], required
        - `lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', required
        - `years` number, 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.
        - `active_at_birth` boolean, required
    - `metadata` VimshottariMetadata, required
      - `calculation_status` 'current', required
      - `practitioner_review` 'not_completed', required
      - `frame` 'apparent_geocentric_sidereal_retained_nutation', required
      - `node_model` 'mean_ascending_and_opposite_descending', required
      - `classification_precision` 'unrounded_binary64', required
      - `interpretations` false, required
      - `year_length` object, required
        - `name` 'julian_365_25_days', required
        - `days` 365.25, required
        - `seconds` 31557600, required
      - `interval` '[start_utc,end_utc)', required
      - `timestamp_resolution` 'microsecond', required
      - `birth_balance_rounding` 'elapsed_duration_floored_to_microseconds', required
      - `cycle_anchor` 'start_of_birth_mahadasha', required
      - `period_timestamps` 'theoretical_offsets_may_extend_beyond_birth_ephemeris_window_no_ephemeris_extrapolation', required
  - VimshottariResponseDepth3: All period timestamps are UTC with microsecond resolution and half-open intervals. Derived period offsets may extend beyond the birth ephemeris window; this does not extrapolate ephemeris positions. Unrounded Moon determines nakshatra and birth balance; elapsed duration is floored to microseconds. Current without practitioner sign-off.
    - `status` 'current', required
    - `type` 'vimshottari', required
    - `input` object, required
      - `birth` NormalizedBirth, required: Synastry normalizes numeric coordinates, zodiac and ayanamsa. Supplied timezone is echoed (including null/empty string); omitted timezone is UTC.
        - `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, nullable, required: IANA timezone name (for example America/New_York). Omission, null, or empty string means UTC for a birth input. Nonexistent or ambiguous local clock-change times return 400; provide the known UTC date/time with timezone UTC instead.
        - `lat` number, required
        - `lon` 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
      - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks', required
      - `depth` 3, required
    - `birth_utc` string, date-time, required: Normalized UTC timestamp; fractional seconds may be present.
    - `zodiac` 'sidereal', required
    - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks', required
    - `moon` object, required
      - `sidereal_longitude` number, required
      - `nakshatra` object, required
        - `index` integer, required
        - `name` string, required
        - `lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', required
        - `pada` integer, required
        - `fraction_elapsed` number, required
    - `birth_balance` object, required
      - `lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', required
      - `subperiod_lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', required
      - `elapsed_years` number, required
      - `remaining_years` number, required
      - `remaining_days` number, 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.
      - `pratyantardasha_lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', required
    - `cycle` object, required
      - `years` 120, 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.
    - `periods` DashaPeriodDepth3[], required
      - `lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', required
      - `years` 7 | 20 | 6 | 10 | 18 | 16 | 19 | 17, 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.
      - `active_at_birth` boolean, required
      - `subperiods` DashaAntardashaDepth3[], required
        - `lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', required
        - `years` number, 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.
        - `active_at_birth` boolean, required
        - `subperiods` DashaSubperiod[], required
          - `lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', required
          - `years` number, 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.
          - `active_at_birth` boolean, required
    - `metadata` VimshottariMetadataDepth3, required
      - `calculation_status` 'current', required
      - `practitioner_review` 'not_completed', required
      - `frame` 'apparent_geocentric_sidereal_retained_nutation', required
      - `node_model` 'mean_ascending_and_opposite_descending', required
      - `classification_precision` 'unrounded_binary64', required
      - `interpretations` false, required
      - `year_length` object, required
        - `name` 'julian_365_25_days', required
        - `days` 365.25, required
        - `seconds` 31557600, required
      - `interval` '[start_utc,end_utc)', required
      - `timestamp_resolution` 'microsecond', required
      - `birth_balance_rounding` 'elapsed_duration_floored_to_microseconds', required
      - `cycle_anchor` 'start_of_birth_mahadasha', required
      - `period_timestamps` 'theoretical_offsets_may_extend_beyond_birth_ephemeris_window_no_ephemeris_extrapolation', required
      - `depth` 3, required
      - `levels` mahadasha,antardasha,pratyantardasha, required
      - `period_counts` object, required
        - `mahadasha` 9, required
        - `antardasha` 81, required
        - `pratyantardasha` 729, required
      - `duration_arithmetic` 'exact_integer_microseconds_proportional_parent_duration', required
  - VimshottariResponseDepth4: Bounded depth-four Vimshottari supported with exactly 6,561 sookshma-dasha leaves and no arbitrary recursion.
    - `status` 'current', required
    - `type` 'vimshottari', required
    - `input` object, required
      - `birth` NormalizedBirth, required: Synastry normalizes numeric coordinates, zodiac and ayanamsa. Supplied timezone is echoed (including null/empty string); omitted timezone is UTC.
        - `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, nullable, required: IANA timezone name (for example America/New_York). Omission, null, or empty string means UTC for a birth input. Nonexistent or ambiguous local clock-change times return 400; provide the known UTC date/time with timezone UTC instead.
        - `lat` number, required
        - `lon` 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
      - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks', required
      - `depth` 4, required
    - `birth_utc` string, date-time, required: Normalized UTC timestamp; fractional seconds may be present.
    - `zodiac` 'sidereal', required
    - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks', required
    - `moon` Moon, required (unresolved $ref)
    - `birth_balance` object, required
      - `lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', required
      - `subperiod_lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', required
      - `elapsed_years` number, required
      - `remaining_years` number, required
      - `remaining_days` number, 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.
      - `pratyantardasha_lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', required
      - `sookshma_dasha_lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', required
    - `cycle` Cycle, required (unresolved $ref)
    - `periods` DashaPeriodDepth4[], required
      - `lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', required
      - `years` 7 | 20 | 6 | 10 | 18 | 16 | 19 | 17, 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.
      - `active_at_birth` boolean, required
      - `subperiods` DashaAntardashaDepth4[], required
        - `lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', required
        - `years` number, 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.
        - `active_at_birth` boolean, required
        - `subperiods` DashaPratyantardashaDepth4[], required
          - `lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', required
          - `years` number, 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.
          - `active_at_birth` boolean, required
          - `subperiods` DashaSookshmaPeriod[], required
            - `lord` 'ketu' | 'venus' | 'sun' | 'moon' | 'mars' | 'rahu' | 'jupiter' | 'saturn' | 'mercury', 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.
            - `active_at_birth` boolean, required
    - `metadata` VimshottariMetadataDepth4, required
      - `calculation_status` CalculationStatus, required (unresolved $ref)
      - `practitioner_review` PractitionerReview, required (unresolved $ref)
      - `frame` Frame, required (unresolved $ref)
      - `node_model` NodeModel, required (unresolved $ref)
      - `classification_precision` ClassificationPrecision, required (unresolved $ref)
      - `interpretations` Interpretations, required (unresolved $ref)
      - `year_length` YearLength, required (unresolved $ref)
      - `interval` Interval, required (unresolved $ref)
      - `timestamp_resolution` TimestampResolution, required (unresolved $ref)
      - `birth_balance_rounding` BirthBalanceRounding, required (unresolved $ref)
      - `cycle_anchor` CycleAnchor, required (unresolved $ref)
      - `period_timestamps` PeriodTimestamps, required (unresolved $ref)
      - `depth` 4, required
      - `levels` mahadasha,antardasha,pratyantardasha,sookshma_dasha, required
      - `period_counts` object, required
        - `mahadasha` 9, required
        - `antardasha` 81, required
        - `pratyantardasha` 729, required
        - `sookshma_dasha` 6561, required
      - `duration_arithmetic` 'exact_integer_microseconds_proportional_parent_duration', required
  - HistoricalVimshottariResponse
    - `schema` 'cosmicephemeris-historical-calculation-v1', required
    - `status` 'historical', required
    - `type` 'vimshottari', required
    - `input` HistoricalVimshottariRequest, 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
      - `ayanamsa` 'lahiri' | 'raman' | 'krishnamurti' | 'fagan_bradley' | 'yukteshwar' | 'sassanian' | 'true_chitra' | 'true_revati' | 'true_pushya' | 'galactic_center_0_sagittarius' | 'galactic_alignment_mardyks'
      - `depth` 2 | 3 | 4: Only 2, 3, or 4; no null, string or boolean. Explicit 2 is output-identical to omission.
    - `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)