---
title: "Human Design Transit Timeline"
method: POST
path: "/human-design/transit-timeline"
tags: ["Human Design"]
---

# Human Design Transit Timeline

`POST /human-design/transit-timeline`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/human-design/transit-timeline`
- 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`

Human Design transits over a date range.
For each transiting body: every gate it enters and leaves (and optionally every line), with retrograde re-entries marked. With natal gates (a subject or a gate list): every window in which a transiting gate completes one of the person's channels.

Gates are fixed arcs of the 302° wheel, so each entry and exit is an exact degree crossing, found to about a second. Range cap, span brackets and cost guard as /predictive/transits/search.

**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 2500 stays per response (a gate stay counts 1, plus 1 per line stay inside it); past that every stay entered before `truncation.resume_from` is returned with `truncated: true`.

**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

- HDTransitTimelineRequest: Human Design transits over a date range. Pass subject or natal_gates to also get channel completions.
  - `bodies` string[]: Transiting bodies. Defaults to all 13 of the Human Design transit set. Earth and South Node ride 180° from the Sun and North Node (the true node, as every HD endpoint uses).
  - `end_date` string, date-time, required: Search range end. A span above your plan's limit (the same cap /predictive/transits/search uses) is rejected with 400 `search_span_limit` before any compute; unmetered service traffic is clamped instead, and window_range says so.
  - `include_lines` boolean: Also return line stays nested in each gate stay (about 6× the entries).
  - `natal_gates` integer[]: Natal gates, when the caller already has the chart. Pass subject or natal_gates, not both.
  - `start_date` string, date-time, required: Search range start, RFC 3339 with a zone.
  - `subject` SubjectRequest: Subject identity and birth data used to compute a chart.
    - `birth_datetime` DateTimeInput, required: Date/time input in ISO-8601, component, or Julian day form. A value that states a clock time must also state its zone, either as a suffix on the string or via the `timezone` field below.
      - `components` object: Date/time components (year, month, day, and optionally hour, minute, second). If hour/minute are present, pass `timezone` alongside them; without it the request is rejected with 400 ambiguous_datetime. Omit the clock entirely and the date resolves to 12:00 UTC.
      - `iso` string: ISO-8601 datetime (supported range 1550–2650 CE, JPL DE440). If it states a clock time it must carry its zone: either a 'Z'/±HH:MM suffix on the string ("1987-07-15T09:01:00-05:00"), or a `timezone` passed alongside it. A zone-less clock time is rejected with 400 ambiguous_datetime — it is not read as UTC. A date-only value ("1987-07-15") has no clock to be ambiguous about and resolves to 12:00 UTC.
      - `julian_day` number, double: Julian Day Number (always UTC-based, so it needs no zone)
      - `timezone` TimezoneInput: Timezone input using IANA names or UTC offsets.
        - `fold_preference` 'earlier' | 'later': Which occurrence to use when the naive local datetime falls in a fall-back fold (a repeated hour): 'earlier' (default — first occurrence) or 'later'. Only meaningful for naive datetimes; the response reports datetime_status=ambiguous_fold either way so the ambiguity can be surfaced to the user.
        - `iana_name` string: IANA timezone name
        - `time_standard` 'auto' | 'standard' | 'daylight': How to interpret a naive local datetime when this zone is applied. 'auto' (default): resolve through the historical-correction overlay where one covers the region/era, then IANA tzdata. 'standard': force the zone's standard (non-daylight) offset — for callers who KNOW the recorded time was standard time regardless of what tzdata believes. 'daylight': force standard+1h. Forcing either marks the resolution tz_confidence=client_override. Ignored when the datetime carries its own Z/±HH:MM suffix or when utc_offset is used.
        - `utc_offset` number: UTC offset in hours
    - `birth_location` BirthLocation, required: Location context for birth data: coordinates plus timezone.
      - `city` string: City name
      - `country` string: Country
      - `elevation` number: Elevation in meters. Accepted and echoed back unchanged; it does not affect planetary positions, which are computed geocentrically. Elevation changes results only where it is taken as the `elev` query parameter: /eclipse/solar/local (local circumstances) and /time/solar-event plus /ephemeris/agro/* (horizon rise/set times).
      - `latitude` CoordinateInput, required: Flexible coordinate input supporting multiple formats.
        - `components` object: Separate degree components with direction
        - `decimal` number: Decimal degrees (-90 to 90 for lat, -180 to 180 for lon)
        - `dms` string: Degrees, minutes, seconds string (e.g., '40°42'46"N')
      - `location_name` string: Birthplace display name (e.g. "Dallas, TX"). Never affects calculations — coordinates and timezone are the only location facts the engine reads. Echoed back verbatim where the response carries an echo block: as subject.location_name on chart routes that echo a subject (natal, draconic, progressed, synastry, natal-transits, overlay, natal/batch items, predictive transit-chart), inside search_summary on /electional/natal-angle-crossings, metadata on /acg/midpoints, and natal on /human-design/transit-chart. Omitted from the response when not sent.
      - `longitude` CoordinateInput, required: Flexible coordinate input supporting multiple formats.
        - `components` object: Separate degree components with direction
        - `decimal` number: Decimal degrees (-90 to 90 for lat, -180 to 180 for lon)
        - `dms` string: Degrees, minutes, seconds string (e.g., '40°42'46"N')
      - `region` string: State/region
      - `timezone` TimezoneInput, required: Timezone input using IANA names or UTC offsets.
        - `fold_preference` 'earlier' | 'later': Which occurrence to use when the naive local datetime falls in a fall-back fold (a repeated hour): 'earlier' (default — first occurrence) or 'later'. Only meaningful for naive datetimes; the response reports datetime_status=ambiguous_fold either way so the ambiguity can be surfaced to the user.
        - `iana_name` string: IANA timezone name
        - `time_standard` 'auto' | 'standard' | 'daylight': How to interpret a naive local datetime when this zone is applied. 'auto' (default): resolve through the historical-correction overlay where one covers the region/era, then IANA tzdata. 'standard': force the zone's standard (non-daylight) offset — for callers who KNOW the recorded time was standard time regardless of what tzdata believes. 'daylight': force standard+1h. Forcing either marks the resolution tz_confidence=client_override. Ignored when the datetime carries its own Z/±HH:MM suffix or when utc_offset is used.
        - `utc_offset` number: UTC offset in hours
    - `gender` string: Gender (optional)
    - `name` string, required: Subject name
    - `notes` string: Additional notes

## Response `200`

Successful Response

- HDTransitTimelineResponse
  - `bodies` HDBodyGateTimeline[], required: One timeline per requested body, in request order.
    - `body` 'Sun' | 'Earth' | 'Moon' | 'Mercury' | 'Venus' | 'Mars' | 'Jupiter' | 'Saturn' | 'Uranus' | 'Neptune' | 'Pluto' | 'North Node' | 'South Node', required: Transiting body.
    - `stays` HDGateStay[], required: Gate stays overlapping the searched range, chronologically.
      - `enter` string, date-time, nullable, required: Moment the body enters, UTC RFC 3339; can be before the search start. Null only when the stay began more than 5 years before the search start.
      - `entered_retrograde` boolean, required: True when the body entered moving retrograde. False when enter is null.
      - `gate` integer, required: Gate number (302° wheel origin, Gate 41 at 2° Aquarius — the same mapping as every HD endpoint).
      - `leave` string, date-time, nullable, required: Moment the body leaves; can be after the search end. Null only when the stay runs more than 5 years past the search end.
      - `left_retrograde` boolean, required: True when the body left moving retrograde. False when leave is null.
      - `line` integer: Line number, on a line stay only.
      - `lines` HDGateStay[]: Line stays tiling this gate stay end to end, when include_lines is true.
  - `channel_windows` HDChannelWindow[], required: Channel completions, sorted by enter (null first). Empty when no natal gates were sent.
    - `body` 'Sun' | 'Earth' | 'Moon' | 'Mercury' | 'Venus' | 'Mars' | 'Jupiter' | 'Saturn' | 'Uranus' | 'Neptune' | 'Pluto' | 'North Node' | 'South Node', required: Transiting body in transit_gate.
    - `center1` string, required: Center at gate1's end.
    - `center2` string, required: Center at gate2's end.
    - `channel_id` string, required: "gate1-gate2", the same id /human-design/transit-chart uses.
    - `enter` string, date-time, nullable, required: When the channel is completed (the body enters transit_gate). Same null rule as HDGateStay.enter.
    - `leave` string, date-time, nullable, required: When the completion ends (the body leaves transit_gate). Same null rule as HDGateStay.leave.
    - `name` string, required: Channel name.
    - `natal_gate` integer, required: The channel gate the natal chart has.
    - `transit_gate` integer, required: The gate the transiting body supplies.
  - `gate_mapping_version` string, required: Gate-wheel convention the gates follow ("hd_gate_line_v1": Gate 41 at 302°).
  - `natal_gates` integer[]: The natal gates used for channel_windows, sorted. Absent when neither subject nor natal_gates was sent.
  - `success` boolean, required
  - `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, required
    - `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.

## Other responses

- `422`: Validation Error

---

[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)