---
title: "List Eclipses"
method: GET
path: "/eclipse/eclipses"
tags: ["eclipse"]
---

# List Eclipses

`GET /eclipse/eclipses`

## Request

- Base URL: `https://stardrift.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://stardrift.ai/eclipse/eclipses`
- Auth: none declared

Every UPCOMING central eclipse, with metadata for the picker.

Past eclipses are filtered out: this list drives a "which eclipse are you
chasing" picker, and an eclipse that has already happened is never the
answer. `include_past=true` returns the full bundled set for a trip still
pinned to one that has been and gone. The per-date endpoints
(`/path/{date}`, `/point`, `/elements/{date}`) are deliberately NOT
filtered, so such a trip still renders.

## Query parameters

- `include_past` boolean

## Response `200`

Successful Response

- EclipsesResponse
  - `eclipses` EclipseListItem[], required
    - `eclipse_date` string, required
    - `eclipse_type` string, required: total / annular / hybrid
    - `label` string, required
    - `greatest_eclipse` GreatestEclipseOut
      - `ut` string, required: Instant of greatest eclipse (UT, HH:MM:SS.s)
      - `lat` number, required
      - `lon` number, required
    - `regions` string, nullable: Where the path goes, in words (api/eclipse/regions.py).
  - `attribution` string

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-18** `f2ae5a397846`: 3 info
  - added the new optional `query` request parameter `include_past`
  - added the non-success response with the status `422`
  - added the optional property `eclipses/items/regions` to the response with the `200` status

[Operation history](https://skmtc.dev/stardrift/apis/stardrift-api/changes/eclipse/eclipses/get.md)

---

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