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

# List Eclipses

`GET /eclipse/eclipses`

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

[Change history](https://skmtc.dev/stardrift/apis/fastapi/changes/eclipse/eclipses/get.md)

---

[API](https://skmtc.dev/stardrift/apis/fastapi.md) · [All operations](https://skmtc.dev/stardrift/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc.dev/stardrift/apis/fastapi/revisions/1060a62bfafc?raw)