---
title: "Search Transit Events"
method: POST
path: "/predictive/transits/search"
tags: ["predictive"]
---

# Search Transit Events

`POST /predictive/transits/search`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/predictive/transits/search`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-OpenEphemeris-API-Key`
  - API key in header `X-API-Key`
  - API key in header `X-Service-Key`

Search for various types of transit events within a date range.
    
    **Features:**
    - Exact crossings of target degrees, several passes per target (`results`)
    - Opt-in orb windows (`orb_deg` / `aspect_orbs`): enter, every exact hit including retrograde re-passes, and leave, per continuous in-orb episode (`windows`), with applying/separating at the range start
    - Natal points × aspects as labelled targets (`natal_points`, `aspects`)
    - Configurable date ranges (plan limits: 1 year on Explorer/PAYG, 5 years on Pro, 10 years on Startup, 40 years on Scale and above)
    
    **Performance:** one sampled track per planet shared by every target; the cost guard counts days × planets × targets.
    
    **Pricing (by requested span, decided before any compute):** up to 1 year (367 days) = 5, up to 3 years (1097 days) = 10, up to 5 years (1828 days) = 15, up to 10 years (3654 days) = 25, up to 20 years (7306 days) = 40, up to 40 years (14611 days) = 70 credits. Plan limits: Explorer/PAYG 1 year, Pro 5 years, Startup 10 years, Scale and Enterprise 40 years. A span above your plan's limit is rejected with 400 `search_span_limit` naming the limit and the bracket that fits — nothing is charged. Any 4xx/5xx outcome is refunded, including a 429 compute_overload shed; rate-limit 429s are refused before anything is charged. Results are capped at 1000 transit events per response; past that the earliest 1000 are returned with `truncated: true` and `truncation.resume_from` to continue from.
    
    **Deadline:** 30 s of compute on every plan. A search that runs out of time returns the bodies it finished with `truncated: true` (reason `deadline`, the unsearched bodies in `truncation.remaining`); if none finished it returns 503 `compute_timeout`, and the credits are refunded.

## Request body

- TransitSearchRequest: Request schema for general transit search. Set orb_deg for enter/exact/leave windows.
  - `aspect_orbs` object: Per-aspect orbs in degrees, keyed by aspect name (e.g. {"conjunction": 3, "square": 2}). Applies to targets built from natal_points × aspects and to search_criteria.aspect_angle; an aspect not listed uses orb_deg. Setting it turns on `windows`.
  - `aspects` string[]: Aspects to search for each natal point. Defaults to the five majors: conjunction, sextile, square, trine, opposition.
  - `end_date` string, date-time, required: Search range end date
  - `natal_points` TransitNatalPoint[]: Natal points to search transits to. Each point × each entry in `aspects` becomes a labelled target (both sides of the zodiac for aspects other than conjunction and opposition). When natal_points is set and target_degrees is not, no default target degrees are added. Hits in `results` for these targets are keyed "<Planet>_<aspect>_<point>@<degree>".
    - `longitude` number, double: Natal ecliptic longitude in degrees, 0-360, in the same zodiac the transits are computed in (tropical). Required — a point without one is rejected, never read as 0°.
    - `name` string, required: Label echoed on every window and hit for this point, e.g. "Sun" or "ASC".
  - `orb_deg` number, double: Opt-in orb windows. When set (or when aspect_orbs is set), the response adds `windows`: one entry per continuous in-orb episode of each planet against each target, with enter, every exact hit, and leave. The default orb for every target; aspect_orbs overrides it per aspect. Greater than 0, at most 15.
  - `planet_names` string[]: Planets to include (validated in route)
  - `search_criteria` object: Additional search criteria (currently not supported by the route; omit it)
  - `start_date` string, date-time, required: Search range start date
  - `target_degrees` number[]: Specific degrees to search for

## Response `200`

Successful Response

- TransitSearchResponse: Response schema for general transit search.
  - `calculation_metadata` CalculationMetadata: Metadata about chart calculations. Relaxed to allow minimal fields used by tests while remaining forward-compatible.
    - `ascendant_on_left` boolean, nullable: When true (default), the Ascendant is placed at the 9 o'clock (West/left) position � matching the convention used by Astro.com, Solar Fire, and all major astrology software. Set to false to use the ecliptic-fixed (Aries-pinned) orientation instead.
    - `ayanamsa` union: Sidereal ayanamsa selection
      - 'lahiri' | 'fagan_bradley' | 'krishnamurti' | 'raman' | 'yukteshwar': Supported sidereal ayanamsa options. All five are computed from the same IAU 2006 general-precession model, so each is epoch-dependent rather than a frozen constant; they differ by up to ~2.3 degrees, which is enough to move a body across a sign boundary. Defaults to lahiri when zodiac_type is sidereal and no system is named.
      - string
    - `calculation_time` number: Legacy calculation time in seconds
    - `calculation_time_ms` number: Processing time at the orchestrator layer in milliseconds
    - `calculation_time_utc` string, date-time: UTC timestamp when the calculation executed
    - `coordinate_reference_frame` string: Coordinate frame the positions are expressed in. The engine computes apparent places referred to the true equator/equinox of date and converts them to the true ecliptic of date, so this reads geocentric_true_ecliptic_of_date.
    - `coordinate_system` union: Coordinate system used (geocentric/topocentric)
      - 'geocentric' | 'topocentric' | 'heliocentric' | 'barycentric': Coordinate system used for calculations.
      - string
    - `delta_t_seconds` number: Delta T (TT - UT1) applied during calculation, in seconds
    - `delta_t_source` union: Source of Delta T values (computation engine, IERS, approximation)
      - 'nasa_jpl' | 'iers' | 'approximation_model': Source of ΔT values used in calculations.
      - string
    - `ephemeris_source` string: Primary ephemeris source (e.g., SuperNOVAS / Calceph)
    - `ephemeris_version` string: Version of the ephemeris data files
    - `fixed_star_catalog` union: Fixed star catalog or subset identifier
      - 'bright_mag3' | 'bright_mag5' | 'royal_stars' | 'parans_key': Fixed star catalog snapshots.
      - string
    - `house_system` union: House system actually used during calculation
      - 'P' | 'K' | 'O' | 'R' | 'C' | 'E' | 'W': Supported house systems.
      - string
    - `include_fixed_stars` boolean: Whether fixed stars were included
    - `julian_day` number, double: Julian Day Number representing the calculation instant
    - `missing_objects` object: Objects that could not be calculated along with reasons
    - `node_source` union: Lunar node/apsides mode requested (true osculating, mean, apsides)
      - 'true_osculating' | 'mean' | 'mean_apsides': Node/apsides calculation modes (SE §2.2).
      - string
    - `object_set` union: Named object set or preset powering the calculation
      - 'traditional_7' | 'modern_10' | 'modern_plus_chiron' | 'asteroids_major' | 'full' | 'custom': Standardized celestial object bundles.
      - string
    - `orb_system_used` string: Aspect orb system applied
    - `precision_level` string: Legacy precision descriptor
    - `precision_summary` PrecisionSummary: Structured precision report for calculation metadata.
      - `max_position_error_arcseconds` number: Maximum validated positional error in arcseconds
      - `max_timing_error_seconds` number: Maximum validated timing error in seconds
      - `notes` string: Additional human-readable context for the precision summary
      - `reference_profile` string: Reference dataset or validation profile used for the comparison
    - `processing_time_ms` number: End-to-end processing time in milliseconds
    - `server_version` string: Build identifier of the engine that produced this response. Moves on every deploy, so it is the signal for resolution-LOGIC changes — the class of change that can move a historical offset without touching overlay data (and therefore without moving tz_overlay_version). Poll both.
    - `sidereal_time` number: Local sidereal time in hours
    - `technique_id` string: High-level technique identifier (e.g., natal, synastry, composite, overlay)
    - `technique_label` string: Human-readable technique label
    - `technique_method` string: Method name within a technique (e.g., davidson, midpoint)
    - `technique_version` string: Technique implementation version (for future-proofing)
    - `time_scale` union: Time scale used for internal calculations (UTC, TT, TDB)
      - 'UTC' | 'TT' | 'TDB': Time scale used for reporting results.
      - string
    - `tz_overlay_hash` string: Content hash of the historical-correction overlay dataset that produced this answer. Stamped only when an overlay row applied (tz_rule_source starts with 'overlay:').
    - `tz_overlay_version` integer: Monotonic version of the historical-correction overlay dataset that produced this answer. Stamped only when an overlay row applied. Tracks overlay DATA only — pair with server_version to also catch resolution-logic changes.
    - `tz_precision` 'statutory' | 'documented' | 'inferred': Sourcing grade of the overlay row that produced the offset: 'statutory' (operative text of a session law or statute verified), 'documented' (contemporary reporting), or 'inferred' (deduced from legal context; verify before relying on it near the row's edges). Stamped only when an overlay row applied.
    - `tz_rule_citation` string: Primary-source citation for the overlay row that produced the offset — statute reference, ICC/agency order number, or documented press/almanac source. Stamped only when an overlay row applied.
    - `zodiac_type` union: Zodiac framework applied (tropical/sidereal)
      - 'tropical' | 'sidereal': Supported zodiac frameworks.
      - string
  - `metadata` PredictiveMetadata, required: Metadata for predictive calculation responses.
    - `accuracy_statement` string: Accuracy information
    - `cache_status` string: Cache hit/miss status
    - `calculation_metadata` CalculationMetadata: Metadata about chart calculations. Relaxed to allow minimal fields used by tests while remaining forward-compatible.
      - `ascendant_on_left` boolean, nullable: When true (default), the Ascendant is placed at the 9 o'clock (West/left) position � matching the convention used by Astro.com, Solar Fire, and all major astrology software. Set to false to use the ecliptic-fixed (Aries-pinned) orientation instead.
      - `ayanamsa` union: Sidereal ayanamsa selection
        - 'lahiri' | 'fagan_bradley' | 'krishnamurti' | 'raman' | 'yukteshwar': Supported sidereal ayanamsa options. All five are computed from the same IAU 2006 general-precession model, so each is epoch-dependent rather than a frozen constant; they differ by up to ~2.3 degrees, which is enough to move a body across a sign boundary. Defaults to lahiri when zodiac_type is sidereal and no system is named.
        - string
      - `calculation_time` number: Legacy calculation time in seconds
      - `calculation_time_ms` number: Processing time at the orchestrator layer in milliseconds
      - `calculation_time_utc` string, date-time: UTC timestamp when the calculation executed
      - `coordinate_reference_frame` string: Coordinate frame the positions are expressed in. The engine computes apparent places referred to the true equator/equinox of date and converts them to the true ecliptic of date, so this reads geocentric_true_ecliptic_of_date.
      - `coordinate_system` union: Coordinate system used (geocentric/topocentric)
        - 'geocentric' | 'topocentric' | 'heliocentric' | 'barycentric': Coordinate system used for calculations.
        - string
      - `delta_t_seconds` number: Delta T (TT - UT1) applied during calculation, in seconds
      - `delta_t_source` union: Source of Delta T values (computation engine, IERS, approximation)
        - 'nasa_jpl' | 'iers' | 'approximation_model': Source of ΔT values used in calculations.
        - string
      - `ephemeris_source` string: Primary ephemeris source (e.g., SuperNOVAS / Calceph)
      - `ephemeris_version` string: Version of the ephemeris data files
      - `fixed_star_catalog` union: Fixed star catalog or subset identifier
        - 'bright_mag3' | 'bright_mag5' | 'royal_stars' | 'parans_key': Fixed star catalog snapshots.
        - string
      - `house_system` union: House system actually used during calculation
        - 'P' | 'K' | 'O' | 'R' | 'C' | 'E' | 'W': Supported house systems.
        - string
      - `include_fixed_stars` boolean: Whether fixed stars were included
      - `julian_day` number, double: Julian Day Number representing the calculation instant
      - `missing_objects` object: Objects that could not be calculated along with reasons
      - `node_source` union: Lunar node/apsides mode requested (true osculating, mean, apsides)
        - 'true_osculating' | 'mean' | 'mean_apsides': Node/apsides calculation modes (SE §2.2).
        - string
      - `object_set` union: Named object set or preset powering the calculation
        - 'traditional_7' | 'modern_10' | 'modern_plus_chiron' | 'asteroids_major' | 'full' | 'custom': Standardized celestial object bundles.
        - string
      - `orb_system_used` string: Aspect orb system applied
      - `precision_level` string: Legacy precision descriptor
      - `precision_summary` PrecisionSummary: Structured precision report for calculation metadata.
        - `max_position_error_arcseconds` number: Maximum validated positional error in arcseconds
        - `max_timing_error_seconds` number: Maximum validated timing error in seconds
        - `notes` string: Additional human-readable context for the precision summary
        - `reference_profile` string: Reference dataset or validation profile used for the comparison
      - `processing_time_ms` number: End-to-end processing time in milliseconds
      - `server_version` string: Build identifier of the engine that produced this response. Moves on every deploy, so it is the signal for resolution-LOGIC changes — the class of change that can move a historical offset without touching overlay data (and therefore without moving tz_overlay_version). Poll both.
      - `sidereal_time` number: Local sidereal time in hours
      - `technique_id` string: High-level technique identifier (e.g., natal, synastry, composite, overlay)
      - `technique_label` string: Human-readable technique label
      - `technique_method` string: Method name within a technique (e.g., davidson, midpoint)
      - `technique_version` string: Technique implementation version (for future-proofing)
      - `time_scale` union: Time scale used for internal calculations (UTC, TT, TDB)
        - 'UTC' | 'TT' | 'TDB': Time scale used for reporting results.
        - string
      - `tz_overlay_hash` string: Content hash of the historical-correction overlay dataset that produced this answer. Stamped only when an overlay row applied (tz_rule_source starts with 'overlay:').
      - `tz_overlay_version` integer: Monotonic version of the historical-correction overlay dataset that produced this answer. Stamped only when an overlay row applied. Tracks overlay DATA only — pair with server_version to also catch resolution-logic changes.
      - `tz_precision` 'statutory' | 'documented' | 'inferred': Sourcing grade of the overlay row that produced the offset: 'statutory' (operative text of a session law or statute verified), 'documented' (contemporary reporting), or 'inferred' (deduced from legal context; verify before relying on it near the row's edges). Stamped only when an overlay row applied.
      - `tz_rule_citation` string: Primary-source citation for the overlay row that produced the offset — statute reference, ICC/agency order number, or documented press/almanac source. Stamped only when an overlay row applied.
      - `zodiac_type` union: Zodiac framework applied (tropical/sidereal)
        - 'tropical' | 'sidereal': Supported zodiac frameworks.
        - string
    - `calculation_type` string, required: Type of calculation performed
    - `nasa_validated` boolean: NASA validation status
    - `performance_note` string: Performance information
    - `processing_time_ms` number, required: Processing time in milliseconds
    - `search_range_years` number: Years searched
  - `results` object, required: Search results organized by criteria
  - `search_range_years` number, required: Years searched
  - `success` boolean, required: Request success status
  - `truncated` boolean: True when the response is not the complete answer to the request — see `truncation` for why and how to continue. Always present.
  - `truncation` ResultTruncation: Present (with `truncated: true`) when a search response is not the complete answer to the request. `reason` says why: `max_events` — the result hit the per-response event cap, and every event before `resume_from` is included; `deadline` — the compute deadline (30 s) expired, and only the bodies not listed in `remaining` were searched. Continue by re-issuing the request with `start_date` = `resume_from` (max_events) or with only the `remaining` bodies (deadline).
    - `hint` string, required: How to fetch the rest, in one sentence.
    - `max_events` integer: The per-response event cap for this endpoint.
    - `reason` 'max_events' | 'deadline', required
    - `remaining` string[]: Bodies that were not searched before the deadline (reason = deadline).
    - `resume_from` string, date-time: Start instant for the follow-up request (reason = max_events).
    - `returned_events` integer, required: Events included in this response.
  - `window_range` TransitWindowRange
    - `clamped` boolean, required: True when end_date was clamped to the tier's maximum search range (unmetered service traffic only; a metered caller over the cap gets 400 `search_span_limit`).
    - `end` string, date-time, required: End of the range actually searched. Earlier than the requested end_date when the tier range cap clamped it.
    - `start` string, date-time, required: Start of the range actually searched, UTC RFC 3339.
  - `windows` TransitOrbWindow[]: Present only when orb_deg or aspect_orbs is set. Orb windows overlapping the searched range, sorted by enter (a null enter first). Unlike `results`, windows are not capped per target: every pass inside the range is reported.
    - `aspect` string: Aspect name, when the target came from natal_points × aspects or search_criteria.aspect_angle.
    - `aspect_angle` number, double: Aspect angle in degrees, when aspect is set.
    - `duration_days` number, double, nullable, required: leave − enter in days. Null when either end is null.
    - `enter` string, date-time, nullable, required: Moment the body enters the orb, UTC RFC 3339. Can be before the search start (the window was already running). Null only when the body is still inside the orb 5 years before the search start — unknown, never guessed.
    - `exacts` TransitWindowExact[], required: Every exact hit inside the window, chronologically — including any that fall outside the search range but belong to a window overlapping it.
      - `is_retrograde` boolean, required: True when the transiting body is moving retrograde at this exact.
      - `time` string, date-time, required: Exact moment, UTC RFC 3339. The same crossing `results` reports, to about a second.
    - `leave` string, date-time, nullable, required: Moment the body leaves the orb. Can be after the search end. Null only when the body is still inside 5 years after the search end.
    - `natal_longitude` number, double: The natal point's longitude, when natal_point is set.
    - `natal_point` string: The natal point's name, for targets built from `natal_points`. Absent for target_degrees and search_criteria targets.
    - `orb_at_start` number, double, nullable, required: Distance from exact, in degrees, at the search start, when the body is inside this window then; null otherwise.
    - `orb_deg` number, double, required: Orb that defines the window: the body is in orb while target-orb <= longitude < target+orb.
    - `phase_at_start` 'applying' | 'separating' | 'exact', nullable, required: Motion relative to the target at the search start, when the body is inside this window then; null when the window starts later.
    - `planet_id` integer, required: Transiting body id.
    - `planet_name` string, required: Transiting body name.
    - `stations` TransitWindowStation[], required: Stations the body makes while inside the orb.
      - `time` string, date-time, required: Station moment, UTC RFC 3339, to about a minute.
      - `type` 'retrograde' | 'direct', required: "retrograde" when the body turns retrograde here, "direct" when it turns direct.
    - `target_longitude` number, double, required: The fixed degree this window is measured against (natal longitude + aspect angle for a natal-point target).

## Other responses

- `400`: Bad Request - Input validation failed
- `422`: Unprocessable Entity - Invalid input format
- `429`: Rate Limit Exceeded - Too many requests
- `500`: Internal Server Error - Calculation failed

---

[API](https://skmtc.dev/openephemeris/apis/open-ephemeris-api.md) · [All operations](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/revisions/d195a769cb89?raw)