---
title: "List Notifications"
method: GET
path: "/notifications"
tags: ["notifications"]
---

# List Notifications

`GET /notifications`

Paginated inbox, most-recent first.

Cursor is the ISO-8601 `created_at` of the last item from the previous
page — strictly less-than to avoid duplicating the boundary row when
two notifications share a microsecond (rare, but possible).

## Query parameters

- `cursor` string, nullable
- `limit` integer

## Response `200`

Successful Response

- NotificationPage
  - `items` NotificationItem[], required
    - `id` string, uuid, required
    - `type` string, required
    - `trip_id` string, uuid, nullable, required
    - `payload` union, required
      - union
        - InvitePayload
          - `type` 'invite'
          - `actor` NotificationActor, required — Snapshot of the user who triggered the notification. Snapshotted at write time so renames/deletions don't rewrite history.
            - `user_id` string, nullable
            - `name` string, nullable
            - `username` string, nullable
            - `email` string, nullable
            - `avatar_color` string, nullable
            - `avatar_url` string, nullable
          - `trip` NotificationTrip
            - `id` string, required
            - `title` string, nullable
            - `hero_image_url` string, nullable
          - `invitation_token` string, nullable
        - MemberJoinedPayload
          - `type` 'member_joined'
          - `actor` NotificationActor, required — Snapshot of the user who triggered the notification. Snapshotted at write time so renames/deletions don't rewrite history.
            - `user_id` string, nullable
            - `name` string, nullable
            - `username` string, nullable
            - `email` string, nullable
            - `avatar_color` string, nullable
            - `avatar_url` string, nullable
          - `trip` NotificationTrip
            - `id` string, required
            - `title` string, nullable
            - `hero_image_url` string, nullable
        - MemberLeftPayload
          - `type` 'member_left'
          - `actor` NotificationActor, required — Snapshot of the user who triggered the notification. Snapshotted at write time so renames/deletions don't rewrite history.
            - `user_id` string, nullable
            - `name` string, nullable
            - `username` string, nullable
            - `email` string, nullable
            - `avatar_color` string, nullable
            - `avatar_url` string, nullable
          - `trip` NotificationTrip
            - `id` string, required
            - `title` string, nullable
            - `hero_image_url` string, nullable
          - `removed_user` NotificationActor — Snapshot of the user who triggered the notification. Snapshotted at write time so renames/deletions don't rewrite history.
            - `user_id` string, nullable
            - `name` string, nullable
            - `username` string, nullable
            - `email` string, nullable
            - `avatar_color` string, nullable
            - `avatar_url` string, nullable
        - ItemAddedPayload
          - `type` 'item_added'
          - `actor` NotificationActor, required — Snapshot of the user who triggered the notification. Snapshotted at write time so renames/deletions don't rewrite history.
            - `user_id` string, nullable
            - `name` string, nullable
            - `username` string, nullable
            - `email` string, nullable
            - `avatar_color` string, nullable
            - `avatar_url` string, nullable
          - `trip` NotificationTrip
            - `id` string, required
            - `title` string, nullable
            - `hero_image_url` string, nullable
          - `counts` object
          - `total` integer
          - `items` AddedItemSnapshot[]
            - `kind` string, required
            - `title` string, required
            - `photo_url` string, nullable
            - `logo_url` string, nullable
            - `day_label` string, nullable
        - PlanEditPayload
          - `type` 'plan_edit'
          - `actor` NotificationActor, required — Snapshot of the user who triggered the notification. Snapshotted at write time so renames/deletions don't rewrite history.
            - `user_id` string, nullable
            - `name` string, nullable
            - `username` string, nullable
            - `email` string, nullable
            - `avatar_color` string, nullable
            - `avatar_url` string, nullable
          - `trip` NotificationTrip
            - `id` string, required
            - `title` string, nullable
            - `hero_image_url` string, nullable
          - `plan_id` string, required
          - `version` integer, required
          - `summary` string, nullable
          - `revision_id` integer, nullable
        - CommentPayload
          - `type` 'comment'
          - `actor` NotificationActor, required — Snapshot of the user who triggered the notification. Snapshotted at write time so renames/deletions don't rewrite history.
            - `user_id` string, nullable
            - `name` string, nullable
            - `username` string, nullable
            - `email` string, nullable
            - `avatar_color` string, nullable
            - `avatar_url` string, nullable
          - `trip` NotificationTrip
            - `id` string, required
            - `title` string, nullable
            - `hero_image_url` string, nullable
          - `scope` 'itinerary_item' | 'plan_note', required
          - `target_id` string, required
          - `target_label` string, nullable
          - `comment_id` string, required
          - `comment_excerpt` string, required
        - MentionPayload — `@username` mention inside a comment. Same fields as `CommentPayload` — the inbox renderer can swap the verb ("commented" → "mentioned you") off the discriminator. Mentioned users get this row INSTEAD of the generic comment row, not in addition to it (the comment fan-out skips them).
          - `type` 'mention'
          - `actor` NotificationActor, required — Snapshot of the user who triggered the notification. Snapshotted at write time so renames/deletions don't rewrite history.
            - `user_id` string, nullable
            - `name` string, nullable
            - `username` string, nullable
            - `email` string, nullable
            - `avatar_color` string, nullable
            - `avatar_url` string, nullable
          - `trip` NotificationTrip
            - `id` string, required
            - `title` string, nullable
            - `hero_image_url` string, nullable
          - `scope` 'itinerary_item' | 'plan_note', required
          - `target_id` string, required
          - `target_label` string, nullable
          - `comment_id` string, required
          - `comment_excerpt` string, required
        - LikePayload
          - `type` 'like'
          - `actor` NotificationActor, required — Snapshot of the user who triggered the notification. Snapshotted at write time so renames/deletions don't rewrite history.
            - `user_id` string, nullable
            - `name` string, nullable
            - `username` string, nullable
            - `email` string, nullable
            - `avatar_color` string, nullable
            - `avatar_url` string, nullable
          - `trip` NotificationTrip
            - `id` string, required
            - `title` string, nullable
            - `hero_image_url` string, nullable
          - `scope` 'itinerary_item' | 'plan_note' | 'comment', required
          - `target_id` string, required
          - `target_label` string, nullable
          - `comment_excerpt` string, nullable
        - BookingMatchedPayload — System notification: bookings imported from the user's inbox were matched to one of their trips (the live, per-trip case). No `actor` — this is system-generated (the email scanner), not a collaborator action, so the inbox renderer reads the copy off the discriminator rather than an actor name (cf. `home_location_needed`). `items` snapshots the matched bookings so the inbox row can show *which* flights/stays/activities landed, mirroring `item_added`.
          - `type` 'booking_matched'
          - `trip` NotificationTrip
            - `id` string, required
            - `title` string, nullable
            - `hero_image_url` string, nullable
          - `counts` object
          - `total` integer
          - `items` AddedItemSnapshot[]
            - `kind` string, required
            - `title` string, required
            - `photo_url` string, nullable
            - `logo_url` string, nullable
            - `day_label` string, nullable
        - BookingImportSummaryPayload — System notification: the first-connect inbox scan built/updated several trips at once. A single summary row (not one per trip) so the initial import doesn't flood the inbox; deep-links to the trips list.
          - `type` 'booking_import_summary'
          - `trip_count` integer
          - `total` integer
          - `counts` object
          - `trips` ImportedTripSnapshot[]
            - `trip_id` string, required
            - `title` string, nullable
            - `count` integer
        - HomeLocationNeededPayload — Synthetic system nudge: the user has no confirmed home location. Unlike collab notifications this row is cleared on *confirmation* (the user saves/accepts a home location), not on inbox view — it's the "busy" indicator of the S0–S3 state machine in HOME_LOCATION_ONBOARDING.md §6, so bulk mark-read deliberately skips it (see routes/notifications.py).
          - `type` 'home_location_needed'
          - `prefilled` boolean
        - FlightCheckInPayload — System notification: check-in has opened for one upcoming flight. `instance_key` is the key the Home block and the scheduled push already share (`api.services.home_blocks.check_in_instance_key`), so the presence of this row is what makes the send idempotent — see `api/services/flight_check_in_reminders.py`.
          - `type` 'flight_check_in'
          - `instance_key` string, required
          - `booking_id` string, required
          - `airline` string, nullable
          - `flight_number` string, nullable
          - `departure_airport` string, required
          - `arrival_airport` string, required
          - `departure_at` string, date-time, required
          - `check_in_url` string, required
        - LeaveForAirportPayload — System notification: the leave-for-airport heads-up or nudge. `phase` is part of the idempotency key: one flight legitimately sends both the evening heads-up and the pre-leave nudge, and each must send once.
          - `type` 'leave_for_airport'
          - `instance_key` string, required
          - `phase` 'heads_up' | 'nudge', required
          - `booking_id` string, required
          - `airline` string, nullable
          - `flight_number` string, nullable
          - `departure_airport` string, required
          - `departure_at` string, date-time, required
          - `leave_by` string, date-time, required
        - SocialImportPayload — System notification: a reel or TikTok shared from outside the app finished importing. No `actor` and no `trip` — this is a Saved-tab list, so the row deep-links to `/saved/<list_id>` rather than through `cta()`'s trip fallback. Carries the same facts as the push (api/services/social_import_notify.py) so the inbox row reads the same as the notification the user already saw. `city` and `author` are stored already cleaned, so the renderer interpolates them.
          - `type` 'social_import'
          - `list_id` string, required
          - `list_title` string, nullable
          - `place_count` integer
          - `first_place` string, nullable
          - `city` string, nullable
          - `author` string, nullable
          - `source` string
          - `cover_image_url` string, nullable
      - object
    - `read_at` string, date-time, nullable, required
    - `created_at` string, date-time, required
  - `next_cursor` string, nullable, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/stardrift/apis/fastapi.md) · [All operations](https://skmtc.dev/stardrift/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/stardrift/fastapi/revisions/00746572572a/schema)