---
title: "Attribute excluded electional samples fairly across interacting criteria"
method: POST
path: "/api/astro/electional-criterion-shapley-audit"
tags: ["Calculations"]
---

# Attribute excluded electional samples fairly across interacting criteria

`POST /api/astro/electional-criterion-shapley-audit`

## Request

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

Evaluates one fixed 15-minute grid, projects it onto every 30- and 60-minute phase, and computes each criterion's exact Shapley contribution to samples excluded by the full rule set. The calculation enumerates every criterion coalition, uses exact rational arithmetic, treats every criterion ordering uniformly, and verifies that criterion contributions sum to the observed excluded-sample total on every evaluable grid. It is interaction-aware attribution, not causal proof, astrological quality scoring, criterion weighting, continuous-time proof, recommendation, interpretation, prediction, probability, or statistical confidence. No licensed catalog, new dependency, or request-time network source is used. One standard quota unit per admitted request; 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.

## Headers

- `X-Cosmic-Ephemeris-Receipt` 'v1'

## Request body

- union
  - ElectionalCriterionShapleyAuditRequest
    - `start_utc` string, date-time, required
    - `end_utc` string, date-time, required
    - `location` GeographicLocation, required: Geographic coordinates in decimal degrees. The server rejects exactly -90 and +90 latitude because angles and houses are undefined at the poles.
      - `lat` union, required: WGS84 decimal latitude. JSON numbers are recommended; numeric strings are accepted by the current engine, then checked for finiteness/range. Exact poles and undefined Ascendant geometry return 400; supported successful latitude is strictly between -90 and 90. Boolean/null/object/array coordinates are invalid.
        - number
        - string
      - `lon` union, required: WGS84 decimal longitude, east positive, within [-180,180]. JSON numbers are recommended; numeric strings are accepted then checked for finiteness/range.
        - number
        - string
    - `profile` union, required
      - object
        - `zodiac` 'tropical', required
      - object
        - `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
    - `filters` ElectionalFilters, required
      - `moon_signs` ElectionalSignName[]
      - `moon_phase_sectors` MoonPhaseSector[]
      - `mercury_motion` 'direct' | 'retrograde'
      - `ascendant_signs` ElectionalSignName[]
      - `aspects` ElectionalAspectFilter[]
        - `body_a` 'sun' | 'moon' | 'mercury' | 'venus' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune' | 'pluto', required
        - `body_b` 'sun' | 'moon' | 'mercury' | 'venus' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune' | 'pluto', required
        - `aspect` 'conjunction' | 'sextile' | 'square' | 'trine' | 'opposition', required
        - `max_orb_degrees` number, required
  - HistoricalElectionalCriterionShapleyAuditRequest: 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.
    - `location` object, required: Geographic coordinates in decimal degrees. The server rejects exactly -90 and +90 latitude because angles and houses are undefined at the poles.
      - `lat` union, required: WGS84 decimal latitude. JSON numbers are recommended; numeric strings are accepted by the current engine, then checked for finiteness/range. Exact poles and undefined Ascendant geometry return 400; supported successful latitude is strictly between -90 and 90. Boolean/null/object/array coordinates are invalid.
        - number
        - string
      - `lon` union, required: WGS84 decimal longitude, east positive, within [-180,180]. JSON numbers are recommended; numeric strings are accepted then checked for finiteness/range.
        - number
        - string
    - `profile` union, required
      - object
        - `zodiac` 'tropical', required
      - object
        - `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
    - `filters` object, required
      - `moon_signs` string[]
      - `moon_phase_sectors` string[]
      - `mercury_motion` 'direct' | 'retrograde'
      - `ascendant_signs` string[]
      - `aspects` object[]
        - `body_a` 'sun' | 'moon' | 'mercury' | 'venus' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune' | 'pluto', required
        - `body_b` 'sun' | 'moon' | 'mercury' | 'venus' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune' | 'pluto', required
        - `aspect` 'conjunction' | 'sextile' | 'square' | 'trine' | 'opposition', required
        - `max_orb_degrees` number, required
    - `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`

Exact interaction-aware exclusion attribution across seven sampling grids

- union
  - ElectionalCriterionShapleyAuditResponse
    - `type` 'electional_criterion_shapley_audit', required
    - `status` 'current', required
    - `input` ElectionalCriterionShapleyAuditRequest, required
      - `start_utc` string, date-time, required
      - `end_utc` string, date-time, required
      - `location` GeographicLocation, required: Geographic coordinates in decimal degrees. The server rejects exactly -90 and +90 latitude because angles and houses are undefined at the poles.
        - `lat` union, required: WGS84 decimal latitude. JSON numbers are recommended; numeric strings are accepted by the current engine, then checked for finiteness/range. Exact poles and undefined Ascendant geometry return 400; supported successful latitude is strictly between -90 and 90. Boolean/null/object/array coordinates are invalid.
          - number
          - string
        - `lon` union, required: WGS84 decimal longitude, east positive, within [-180,180]. JSON numbers are recommended; numeric strings are accepted then checked for finiteness/range.
          - number
          - string
      - `profile` union, required
        - object
          - `zodiac` 'tropical', required
        - object
          - `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
      - `filters` ElectionalFilters, required
        - `moon_signs` ElectionalSignName[]
        - `moon_phase_sectors` MoonPhaseSector[]
        - `mercury_motion` 'direct' | 'retrograde'
        - `ascendant_signs` ElectionalSignName[]
        - `aspects` ElectionalAspectFilter[]
          - `body_a` 'sun' | 'moon' | 'mercury' | 'venus' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune' | 'pluto', required
          - `body_b` 'sun' | 'moon' | 'mercury' | 'venus' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune' | 'pluto', required
          - `aspect` 'conjunction' | 'sextile' | 'square' | 'trine' | 'opposition', required
          - `max_orb_degrees` number, required
    - `attribution_status` 'indeterminate_no_evaluable_samples' | 'indeterminate_incomplete_grid_evidence' | 'no_exclusions_observed' | 'exact_shapley_attributions_observed', required
    - `criteria` ElectionalCriterionShapleyCriterion[], required
      - `id` string, required
      - `kind` 'moon_signs' | 'moon_phase_sectors' | 'mercury_motion' | 'ascendant_signs' | 'aspect', required
      - `grid_results` ElectionalCriterionShapleyGridResult[], required
        - `criterion_id` string, required
        - `criterion_kind` 'moon_signs' | 'moon_phase_sectors' | 'mercury_motion' | 'ascendant_signs' | 'aspect', required
        - `grid_id` string, required
        - `status` 'evaluable' | 'unavailable', required
        - `available_sample_count` integer, required
        - `full_criteria_matching_sample_count` integer, nullable, required
        - `full_criteria_excluded_sample_count` integer, nullable, required
        - `permutation_count` 1 | 2 | 6 | 24 | 120 | 720 | 5040 | 40320, required
        - `coalition_context_count` 1 | 2 | 4 | 8 | 16 | 32 | 64 | 128, required
        - `marginal_exclusion_sum_across_permutations` integer, nullable, required
        - `shapley_exclusion_sample_count` ElectionalCriterionShapleyFraction, required
          - `numerator` integer, required
          - `denominator` integer, required
        - `shapley_exclusion_share` ElectionalCriterionShapleyFraction, required
          - `numerator` integer, required
          - `denominator` integer, required
        - `minimum_marginal_exclusion_sample_count` integer, nullable, required
        - `maximum_marginal_exclusion_sample_count` integer, nullable, required
        - `zero_contribution` boolean, nullable, required
      - `evaluable_grid_count` integer, required
      - `positive_contribution_grid_count` integer, required
      - `zero_contribution_grid_count` integer, required
    - `samples` ElectionalFeasibilityAuditSample[], required
      - `id` string, required
      - `utc` string, date-time, required: Normalized UTC timestamp; fractional seconds may be present.
      - `status` 'available' | 'unavailable', required
      - `reason_code` 'undefined_for_input_geometry', nullable, required
      - `matches_all` boolean, nullable, required
      - `matched_criterion_ids` string[], nullable, required
      - `failed_criterion_ids` string[], nullable, required
      - `criteria` ElectionalRobustnessAuditEvaluation[], nullable, required
        - `id` string, required
        - `kind` 'moon_signs' | 'moon_phase_sectors' | 'mercury_motion' | 'ascendant_signs' | 'aspect', required
        - `matched` boolean, required
        - `observed` union, required
          - 'Aries' | 'Taurus' | 'Gemini' | 'Cancer' | 'Leo' | 'Virgo' | 'Libra' | 'Scorpio' | 'Sagittarius' | 'Capricorn' | 'Aquarius' | 'Pisces'
          - 'new_moon' | 'waxing_crescent' | 'first_quarter' | 'waxing_gibbous' | 'full_moon' | 'waning_gibbous' | 'last_quarter' | 'waning_crescent'
          - 'direct' | 'retrograde' | 'stationary'
          - number
    - `grids` ElectionalCriterionShapleyGrid[], required
      - `id` string, required
      - `sample_minutes` 15 | 30 | 60, required
      - `phase_offset_minutes` 0 | 15 | 30 | 45, required
      - `sample_count` integer, required
      - `available_sample_count` integer, required
      - `unavailable_sample_count` integer, required
      - `sample_ids` string[], required
      - `status` 'evaluable' | 'unavailable', required
      - `full_criteria_matching_sample_count` integer, nullable, required
      - `full_criteria_excluded_sample_count` integer, nullable, required
      - `subset_evaluation_count` integer, required
      - `attribution_sum_exclusion_sample_count` ElectionalCriterionShapleyFraction, required
        - `numerator` integer, required
        - `denominator` integer, required
      - `efficiency_verified` boolean, nullable, required
    - `summary` object, required
      - `finest_sample_count` integer, required
      - `finest_available_sample_count` integer, required
      - `finest_unavailable_sample_count` integer, required
      - `criterion_count` integer, required
      - `grid_count` unknown, required
      - `evaluable_grid_count` integer, required
      - `unevaluable_grid_count` integer, required
      - `unevaluable_grid_ids` string[], required
      - `subset_evaluation_count` integer, required
      - `marginal_coalition_context_count` integer, required
      - `returned_criterion_grid_attribution_count` integer, required
      - `efficiency_verified_grid_count` integer, required
    - `fallback` object, required
      - `performed` unknown, required
      - `selected_system` unknown, required
    - `metadata` object, required
      - `model` 'cosmicephemeris-electional-criterion-shapley-audit-v1', required
      - `ephemeris` 'JPL-DE440', required
      - `sampling_method` 'single_15_minute_grid_with_all_30_and_60_minute_phase_projections', required
      - `interval` 'start_inclusive_end_exclusive', required
      - `finest_sample_minutes` unknown, required
      - `grid_specs` object[], required
        - `sample_minutes` 15 | 30 | 60, required
        - `phase_offset_minutes` 0 | 15 | 30 | 45, required
      - `phase_offset_origin` 'request_start', required
      - `maximum_interval_days` unknown, required
      - `maximum_chart_evaluations` unknown, required
      - `maximum_criterion_count` unknown, required
      - `maximum_grid_count` unknown, required
      - `maximum_subset_count_per_grid` unknown, required
      - `maximum_subset_evaluation_count` unknown, required
      - `maximum_in_memory_subset_sample_projections` unknown, required
      - `maximum_permutation_count` unknown, required
      - `maximum_marginal_coalition_context_count` unknown, required
      - `maximum_marginal_contribution_sum_across_permutations` unknown, required
      - `maximum_returned_criterion_grid_attribution_count` unknown, required
      - `value_function` 'available_sample_count_minus_matching_sample_count_for_the_enforced_criterion_coalition', required
      - `attribution_method` 'exact_shapley_value_uniform_over_all_criterion_orderings', required
      - `efficiency_identity` 'sum_of_criterion_shapley_exclusion_values_equals_samples_excluded_by_all_criteria', required
      - `exact_fraction_arithmetic` unknown, required
      - `criterion_weights_applied` unknown, required
      - `floating_point_comparison` unknown, required
      - `chart_recalculation_for_grid_projections` unknown, required
      - `unavailable_samples_excluded_from_attribution` unknown, required
      - `continuous_time_guarantee` unknown, required
      - `unsampled_instants_evaluated` unknown, required
      - `causal_attribution` unknown, required
      - `astrological_quality_ranking` unknown, required
      - `recommendations` unknown, required
      - `interpretations` unknown, required
      - `predictions` unknown, required
      - `statistical_confidence` unknown, required
      - `request_time_network` unknown, required
    - `receipt` CalculationReceipt
      - `schema` 'cosmicephemeris-calculation-receipt-v1', required
      - `kid` string, required
      - `algorithm` 'Ed25519', required
      - `canonicalization` 'cosmicephemeris-canonical-data-v1', required
      - `input_normalization` 'public-request-canonical-data-v1', required
      - `route` string, required
      - `release` string, required
      - `issued_at` string, date-time, required
      - `normalized_input_sha256` string, required
      - `result_sha256` string, required
      - `calculation_profile` object, required
      - `service_dataset_versions` object, required
      - `calculation_fingerprint` string, required
      - `verification_uri` string, required
      - `signature` string, required
  - HistoricalElectionalCriterionShapleyAuditElectionalCriterionShapleyAuditResponse
    - `schema` 'cosmicephemeris-historical-calculation-v1', required
    - `status` 'historical', required
    - `type` 'electional-criterion-shapley-audit', required
    - `input` HistoricalElectionalCriterionShapleyAuditRequest, 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.
      - `location` object, required: Geographic coordinates in decimal degrees. The server rejects exactly -90 and +90 latitude because angles and houses are undefined at the poles.
        - `lat` union, required: WGS84 decimal latitude. JSON numbers are recommended; numeric strings are accepted by the current engine, then checked for finiteness/range. Exact poles and undefined Ascendant geometry return 400; supported successful latitude is strictly between -90 and 90. Boolean/null/object/array coordinates are invalid.
          - number
          - string
        - `lon` union, required: WGS84 decimal longitude, east positive, within [-180,180]. JSON numbers are recommended; numeric strings are accepted then checked for finiteness/range.
          - number
          - string
      - `profile` union, required
        - object
          - `zodiac` 'tropical', required
        - object
          - `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
      - `filters` object, required
        - `moon_signs` string[]
        - `moon_phase_sectors` string[]
        - `mercury_motion` 'direct' | 'retrograde'
        - `ascendant_signs` string[]
        - `aspects` object[]
          - `body_a` 'sun' | 'moon' | 'mercury' | 'venus' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune' | 'pluto', required
          - `body_b` 'sun' | 'moon' | 'mercury' | 'venus' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune' | 'pluto', required
          - `aspect` 'conjunction' | 'sextile' | 'square' | 'trine' | 'opposition', required
          - `max_orb_degrees` number, required
      - `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.
- `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.
- `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)