---
title: "Vedic events over a date range"
method: POST
path: "/v1/astro/events"
tags: ["Advanced"]
---

# Vedic events over a date range

`POST /v1/astro/events`

## Request

- Base URL: `https://api.asterwise.com`
- URL: `https://api.asterwise.com/v1/astro/events`
- Auth: HTTP bearer

One timeline of everything that happens to a chart over 1 to 31 days, each event with its exact time. Sidereal sign ingresses with the new sign's house from the natal Moon, stations, Moon nakshatra changes with Tarabala, Moon sign changes with Chandrabala, exact degree conjunctions with natal planets, eclipses with their contacts, Purnima and Amavasya (the exact full and new Moon, with the tithi's start and end), and Vimshottari dasha changes (to the day). Each event carries the verdict its own rule gives, or null. No weighting.

## Request body

- VedicEventsRequest
  - `from_date` string, nullable: First day (YYYY-MM-DD, civil day in target_timezone). Defaults to today in the birth timezone.
  - `days` integer: Number of civil days, 1 to 31 (7 for a week, 30 for a month).
  - `target_timezone` string, nullable: IANA timezone that defines the days and local times. Defaults to the birth timezone.
  - `location` string, nullable: City name to resolve to lat/lon/tz automatically. Example: 'Mumbai' or 'New Delhi, India'. If provided, latitude, longitude and timezone are not required.
  - `name` string: Person name associated with the birth record
  - `date` string, required: Birth date in YYYY-MM-DD format
  - `time` string, nullable: Birth time in HH:MM 24-hour format. If omitted, sunrise chart is used as fallback.
  - `latitude` number, nullable: Latitude. Required if location not provided.
  - `longitude` number, nullable: Longitude. Required if location not provided.
  - `timezone` string, nullable: IANA timezone. Required if location not provided (unless utc_offset is given). For dates before the zone adopted a standard time, the birthplace's local mean time (longitude / 15 hours) is used.
  - `utc_offset` string, nullable: Optional explicit UTC offset of the birth time, as ±HH:MM or ±HH:MM:SS (e.g. '+04:51:31' for Bombay mean time). Overrides the offset `timezone` would give. Use it when the birth record states the offset, or for historical local times the IANA database cannot represent.
  - `ayanamsa` 'lahiri' | 'raman' | 'kp' | 'tropical': Sidereal ayanamsa mode used in calculations
  - `target_latitude` number, nullable: Place for the Moon's day boundaries. Defaults to the birthplace.
  - `target_longitude` number, nullable: Longitude of that place, east positive. Defaults to the birthplace.

## Response `200`

Successful Response

- ApiResponseRangeEventsResponse
  - `success` boolean: True if the request succeeded
  - `message` string: Human-readable status message
  - `data` RangeEventsResponse, required
    - `birth_time_provided` boolean, required
    - `start_date` string, required
    - `end_date` string, required
    - `days` integer, required
    - `timezone` string, required
    - `range_start_utc` string, required
    - `range_end_utc` string, required
    - `natal` object, required
    - `events` RangeEvent[], required: All events in time order.
      - `kind` string, required: Event kind; see kinds in the response.
      - `planet` string, nullable
      - `title` string, required
      - `time_utc` string, required: ISO 8601 UTC with Z.
      - `time_local` string, required: ISO 8601 local time with offset, in target_timezone.
      - `time_precision` string, required: second, or day for events known only to the day (dasha changes, profection years).
      - `detail` object, required
      - `verdict` 'favorable' | 'unfavorable' | 'neutral', nullable
      - `verdict_rule` string, nullable
      - `rule_source` string, nullable
      - `significations` string[], required
      - `depends_on_birth_time` boolean, required
    - `kinds` object, required
    - `note` string, required

## Other responses

- `401`: Authentication failed
- `403`: Authorization failed
- `404`: Resource not found
- `413`: Payload too large
- `422`: Validation error
- `429`: Rate limit exceeded
- `500`: Internal error
- `502`: Upstream provider error
- `503`: Service unavailable

---

[API](https://skmtc.dev/asterwise/apis/asterwise-api.md) · [All operations](https://skmtc.dev/asterwise/apis/asterwise-api/llms.txt) · [OpenAPI document](https://skmtc.dev/asterwise/apis/asterwise-api/revisions/3c4bbb1194e2?raw)