---
title: "List Bookings"
method: GET
path: "/v1/bookings"
tags: ["mcp-server"]
---

# List Bookings

`GET /v1/bookings`

The user's bookings — imported from email (Gmail scan, forwarded
confirmations, in-chat paste) and sold first-party — in the exact shape
the in-app Bookings page renders, so a flight comes back with its
card_data and its editable ExtractedFlight.

## Query parameters

- `booking_type` 'flight' | 'hotel' | 'rail' | 'road' | 'car_rental' | 'event', nullable
- `trip_id` string, uuid, nullable

## Response `200`

Successful Response

- BookingsResponse
  - `bookings` union[], required
    - union
      - FlightBookingItem
        - `id` string, required
        - `event_date` string, nullable, required
        - `created_at` string, required
        - `confirmation_number` string, nullable, required
        - `status` 'active' | 'cancelled'
        - `gmail_link` string, nullable
        - `import_kind` 'email' | 'image' | 'text', nullable
        - `import_link` string, nullable
        - `import_sources` ImportSource[]
          - `kind` 'email' | 'image' | 'text', required
          - `link` string, nullable
          - `created_at` string, date-time, required
        - `source` 'email_import' | 'first_party'
        - `trip_id` string, nullable
        - `trip_title` string, nullable
        - `review` BookingReview
          - `question` 'which_trip' | 'is_this_yours', required
          - `travelers` string[]
          - `nudge` boolean
        - `booking_type` 'flight'
        - `card_data` FlightCardData, required — Flight card data for frontend - wraps Journey with card metadata. This is the serialization format sent to the frontend FlightCard component. It converts from the internal Journey model to the frontend contract.
          - `type` 'one-way' | 'round-trip' | 'multi-city', required
          - `journeys` ApiModelsFlightCardJourneyDisplay[], required
            - `direction` 'outbound' | 'return', nullable
            - `segments` SegmentDisplay[], required
              - …
            - `total_duration_in_minutes` integer, required
            - `departure_date` string, date-time, nullable
            - `arrival_date` string, date-time, nullable
          - `cash_details` ApiModelsFlightCardCashDisplay — Frontend format for cash pricing.
            - `type` 'cash'
            - `price` number, nullable
            - `currency` string
          - `cabin_class` string, nullable
          - `booking_links` BookingLink[], nullable
            - `link` string, required
            - `label` string, required
            - `price` number, nullable
            - `currency` string, nullable
            - `primary` boolean
            - `fare_name` string, nullable
            - `free_carry_on` integer, nullable
            - `free_checked_bags` integer, nullable
          - `adults` integer
          - `children` integer
          - `booking_token` string, nullable
          - `departure_token` string, nullable
          - `return_date` string, nullable
          - `__index` integer, required
          - `__tool_call_id` string, required
          - `message_id` string, nullable
          - `booking_links_status` string, nullable
          - `confirmation_number` string, nullable
          - `is_booked` boolean
          - `is_user_import` boolean
          - `user_edited` boolean
          - `award_details` object, nullable
        - `edit_data` ExtractedFlightOutput, required — Complete flight booking extracted from user message. For one-way: all segments in outbound_segments, return_segments empty For round-trip: outbound_segments has flights TO destination, return_segments has flights BACK from destination
          - `type` 'one-way' | 'round-trip'
          - `outbound_segments` ExtractedFlightSegment[], required — Segments going TO the destination
            - `departure_airport` string, required — 3-letter IATA code (e.g., 'SFO')
            - `arrival_airport` string, required — 3-letter IATA code (e.g., 'JFK')
            - `departure_datetime` string, date-time, required — Departure date and time (local time, no timezone)
            - `arrival_datetime` string, date-time, nullable — Arrival date and time (local time, no timezone)
            - `duration_minutes` integer, nullable — Flight duration in minutes if mentioned (e.g., '16h 35m' = 995)
            - `flight_number` string, nullable — Flight number (e.g., 'UA123')
            - `airline` string, nullable — Airline name
            - `cabin_class` string, nullable — Cabin class (e.g., 'Economy', 'Premium Economy', 'Business', 'First')
            - `seat` string, nullable — Seat assignment if shown (e.g., '14A', '2K')
            - `aircraft_type_iata` string, nullable — IATA aircraft type code (e.g., '77W', '320')
            - `aircraft_type_icao` string, nullable — ICAO aircraft type code (e.g., 'B77W', 'A320')
            - `tail_number` string, nullable — Aircraft registration number (e.g., 'N12345')
            - `departure_terminal` string, nullable — Departure terminal (e.g., 'T1', 'B')
            - `arrival_terminal` string, nullable — Arrival terminal
            - `departure_country` string, nullable — Departure country ISO code (e.g., 'US')
            - `arrival_country` string, nullable — Arrival country ISO code (e.g., 'GB')
            - `distance_km` number, nullable — Great-circle distance in kilometers
            - `number_of_stops` integer, nullable — Number of intermediate stops (0 for non-stop)
            - `flight_state` string, nullable — Flight state from OAG (e.g., 'Scheduled', 'InGate', 'Cancelled')
            - `pre_oag_departure_datetime` string, date-time, nullable — The ticket's own departure time, recorded the first time OAG touches this segment and never overwritten — the recovery value if an enrichment adjusts wrongly.
            - `pre_oag_arrival_datetime` string, date-time, nullable — The ticket's own arrival time; see pre_oag_departure_datetime.
            - `departure_datetime_utc` string, date-time, nullable — Authoritative departure instant from OAG, timezone-aware UTC. The naive departure_datetime stays local wall-clock at the airport.
            - `arrival_datetime_utc` string, date-time, nullable — Authoritative arrival instant from OAG, timezone-aware UTC. The naive arrival_datetime stays local wall-clock at the airport.
          - `return_segments` ExtractedFlightSegment[] — Segments coming BACK from destination (empty for one-way)
            - `departure_airport` string, required — 3-letter IATA code (e.g., 'SFO')
            - `arrival_airport` string, required — 3-letter IATA code (e.g., 'JFK')
            - `departure_datetime` string, date-time, required — Departure date and time (local time, no timezone)
            - `arrival_datetime` string, date-time, nullable — Arrival date and time (local time, no timezone)
            - `duration_minutes` integer, nullable — Flight duration in minutes if mentioned (e.g., '16h 35m' = 995)
            - `flight_number` string, nullable — Flight number (e.g., 'UA123')
            - `airline` string, nullable — Airline name
            - `cabin_class` string, nullable — Cabin class (e.g., 'Economy', 'Premium Economy', 'Business', 'First')
            - `seat` string, nullable — Seat assignment if shown (e.g., '14A', '2K')
            - `aircraft_type_iata` string, nullable — IATA aircraft type code (e.g., '77W', '320')
            - `aircraft_type_icao` string, nullable — ICAO aircraft type code (e.g., 'B77W', 'A320')
            - `tail_number` string, nullable — Aircraft registration number (e.g., 'N12345')
            - `departure_terminal` string, nullable — Departure terminal (e.g., 'T1', 'B')
            - `arrival_terminal` string, nullable — Arrival terminal
            - `departure_country` string, nullable — Departure country ISO code (e.g., 'US')
            - `arrival_country` string, nullable — Arrival country ISO code (e.g., 'GB')
            - `distance_km` number, nullable — Great-circle distance in kilometers
            - `number_of_stops` integer, nullable — Number of intermediate stops (0 for non-stop)
            - `flight_state` string, nullable — Flight state from OAG (e.g., 'Scheduled', 'InGate', 'Cancelled')
            - `pre_oag_departure_datetime` string, date-time, nullable — The ticket's own departure time, recorded the first time OAG touches this segment and never overwritten — the recovery value if an enrichment adjusts wrongly.
            - `pre_oag_arrival_datetime` string, date-time, nullable — The ticket's own arrival time; see pre_oag_departure_datetime.
            - `departure_datetime_utc` string, date-time, nullable — Authoritative departure instant from OAG, timezone-aware UTC. The naive departure_datetime stays local wall-clock at the airport.
            - `arrival_datetime_utc` string, date-time, nullable — Authoritative arrival instant from OAG, timezone-aware UTC. The naive arrival_datetime stays local wall-clock at the airport.
          - `price` number, nullable — Total cash price if mentioned (null if fully award-booked)
          - `currency` string — ISO 4217 currency code (e.g., USD, EUR, JPY)
          - `award` AwardPayment — Payment made with loyalty miles/points.
            - `amount` integer, nullable — Number of miles/points used (e.g., 800, 25000)
            - `unit` 'miles' | 'points', required — 'miles' or 'points'
            - `account` string, nullable — Loyalty account identifier if shown (e.g., 'MileagePlus XXXXX205', 'Bonvoy XXXX1234')
          - `confirmation_number` string, nullable
          - `booking_reference` string, nullable — Airline PNR / record locator (6-char alphanumeric, e.g., 'ABCDEF'). Different from confirmation_number which may be an OTA/agent booking code.
          - `eticket_number` string, nullable — E-ticket number (typically 13 digits, e.g., '0012345678901')
          - `fare_class` string, nullable — Fare/booking class letter (e.g., 'Y', 'B', 'J', 'W')
          - `checked_bags` integer, nullable — Number of checked bags included or purchased
          - `carry_on_bags` integer, nullable — Number of carry-on bags included
          - `check_in_url` string, nullable — Online check-in URL if present in the email
          - `oag_enriched_at` string, nullable — ISO timestamp when OAG enrichment was applied
          - `passenger_count` integer, nullable — Number of adult passengers on this booking (e.g., 2 passengers)
          - `passenger_names` string[] — Names of passengers if listed (e.g., ['John Smith', 'Jane Smith'])
          - `children` integer, nullable — Number of child passengers (aged 2-11)
          - `infants` integer, nullable — Number of infant passengers (under 2)
      - HotelBookingItem
        - `id` string, required
        - `event_date` string, nullable, required
        - `created_at` string, required
        - `confirmation_number` string, nullable, required
        - `status` 'active' | 'cancelled'
        - `gmail_link` string, nullable
        - `import_kind` 'email' | 'image' | 'text', nullable
        - `import_link` string, nullable
        - `import_sources` ImportSource[]
          - `kind` 'email' | 'image' | 'text', required
          - `link` string, nullable
          - `created_at` string, date-time, required
        - `source` 'email_import' | 'first_party'
        - `trip_id` string, nullable
        - `trip_title` string, nullable
        - `review` BookingReview
          - `question` 'which_trip' | 'is_this_yours', required
          - `travelers` string[]
          - `nudge` boolean
        - `booking_type` 'hotel'
        - `card_data` HotelCardData, required — Hotel card data for frontend - extends HotelOptionOutput with card metadata. This is the serialization format sent to the frontend HotelCard component. It converts from HotelOptionOutput (cached tool result) plus enrichment data.
          - `name` string, required
          - `price` number, nullable
          - `price_display` string, nullable
          - `price_before_taxes` number, nullable
          - `total_price` number, nullable
          - `total_price_display` string, nullable
          - `rating` number, nullable
          - `reviews` integer, nullable
          - `hotel_class` integer, nullable
          - `link` string, nullable
          - `description` string, nullable
          - `check_in_time` string, nullable
          - `check_out_time` string, nullable
          - `amenities` string[]
          - `essential_info` string[]
          - `latitude` number, nullable
          - `longitude` number, nullable
          - `location_rating` number, nullable
          - `nearby_places` object[]
          - `currency` string
          - `property_token` string, nullable
          - `thumbnail` string, nullable
          - `thumbnail_thumbhash` string, nullable
          - `price_tier` string, nullable
          - `source` string, nullable
          - `feed` 'b2c' | 'cug', nullable
          - `hotel_id` string, nullable
          - `rooms` RoomOption[]
            - `offer_id` string, required
            - `room_name` string, required
            - `mapped_room_id` integer, nullable
            - `bed_summary` string, nullable
            - `size_sqft` integer, nullable
            - `max_occupancy` integer, nullable
            - `board_type` string, nullable
            - `board_name` string, nullable
            - `refundable` boolean
            - `cancel_until` string, nullable
            - `price_per_night` number, nullable
            - `total_price` number, nullable
            - `initial_price` number, nullable
            - `taxes_included` boolean, nullable
            - `currency` string
            - `photos` string[]
            - `amenities` string[]
            - `why` string, nullable
          - `__index` integer, required
          - `__tool_call_id` string, required
          - `message_id` string, nullable
          - `check_in_date` string, required
          - `check_out_date` string, required
          - `adults` integer, nullable
          - `children` integer, nullable
          - `children_ages` string, nullable
          - `booking_links` BookingLink[]
            - `link` string, required
            - `label` string, required
            - `price` number, nullable
            - `currency` string, nullable
            - `primary` boolean
            - `fare_name` string, nullable
            - `free_carry_on` integer, nullable
            - `free_checked_bags` integer, nullable
          - `booking_links_status` string
          - `additional_images` string[]
          - `additional_images_thumbhashes` string[]
          - `reviews_breakdown` unknown[]
            - unknown
          - `sample_reviews` unknown[]
            - unknown
          - `address` string, nullable
          - `confirmation_number` string, nullable
          - `is_booked` boolean
          - `taxes_and_fees` number, nullable
          - `is_user_import` boolean
          - `source_reference` SourceReference — Reference to a cached tool result for tracking itinerary item sources. ``source`` distinguishes provenance: ``api`` (an AI/tool search result), ``user_import`` (parsed from the user's email — renders a "From email" badge and the imageless cost-breakdown card), ``user_manual`` (added by hand via the "Add stay" form — a normal image-carrying card, no badge), and ``user_booking`` (WE sold it — a first-party reservation taken through our own checkout; see api/services/hotel_booking_stay.py). ``user_booking`` is deliberately NOT ``user_import``: the item did not come from the user's inbox, and a "From email" badge on a booking we took money for would be a lie. Frontends branch only on ``user_import``, so the new value falls through to the ordinary card.
            - `tool_call_id` string, required
            - `result_index` integer, required
            - `source` 'api' | 'user_import' | 'user_manual' | 'user_booking'
          - `place_id` string, nullable
      - RailBookingItem
        - `id` string, required
        - `event_date` string, nullable, required
        - `created_at` string, required
        - `confirmation_number` string, nullable, required
        - `status` 'active' | 'cancelled'
        - `gmail_link` string, nullable
        - `import_kind` 'email' | 'image' | 'text', nullable
        - `import_link` string, nullable
        - `import_sources` ImportSource[]
          - `kind` 'email' | 'image' | 'text', required
          - `link` string, nullable
          - `created_at` string, date-time, required
        - `source` 'email_import' | 'first_party'
        - `trip_id` string, nullable
        - `trip_title` string, nullable
        - `review` BookingReview
          - `question` 'which_trip' | 'is_this_yours', required
          - `travelers` string[]
          - `nudge` boolean
        - `booking_type` 'rail'
        - `card_data` ImportedRailCardData, required — Flat RailOption-shaped card payload for an imported rail journey. The frontend RailCard component renders the RailOption shape (travel_legs, departure_datetime, …), NOT the nested RailCardData — sending RailCardData hits the component's empty-travel_legs guard and renders nothing. This model is the single typed source of that flat shape; both the chat hydration dict and GET /bookings use it.
          - `departure_datetime` string, date-time, required
          - `arrival_datetime` string, date-time, required
          - `duration_seconds` integer, required
          - `duration_display` string, required
          - `departure_id` string, required
          - `arrival_id` string, required
          - `train_names` string[]
          - `num_transfers` integer
          - `coach_price` number, nullable
          - `currency` string
          - `travel_legs` ImportedRailLeg[]
            - `train_id` string, required
            - `route` string
            - `departure_id` string, required
            - `arrival_id` string, required
            - `departure_time` string, required
            - `arrival_time` string, required
            - `duration` string, required
            - `operator_logo` string, nullable
          - `booking_date` string, required
          - `booking_links` BookingLink[]
            - `link` string, required
            - `label` string, required
            - `price` number, nullable
            - `currency` string, nullable
            - `primary` boolean
            - `fare_name` string, nullable
            - `free_carry_on` integer, nullable
            - `free_checked_bags` integer, nullable
          - `confirmation_number` string, nullable
          - `is_booked` boolean
          - `is_user_import` boolean
          - `ground_mode` string
      - RoadBookingItem
        - `id` string, required
        - `event_date` string, nullable, required
        - `created_at` string, required
        - `confirmation_number` string, nullable, required
        - `status` 'active' | 'cancelled'
        - `gmail_link` string, nullable
        - `import_kind` 'email' | 'image' | 'text', nullable
        - `import_link` string, nullable
        - `import_sources` ImportSource[]
          - `kind` 'email' | 'image' | 'text', required
          - `link` string, nullable
          - `created_at` string, date-time, required
        - `source` 'email_import' | 'first_party'
        - `trip_id` string, nullable
        - `trip_title` string, nullable
        - `review` BookingReview
          - `question` 'which_trip' | 'is_this_yours', required
          - `travelers` string[]
          - `nudge` boolean
        - `booking_type` 'road'
        - `card_data` RoadCardData, required — Road transport card data for the frontend RoadCard component. Flat single-ride shape: road journeys are always one leg with one RoadSegment (a round trip is two separate journeys).
          - `operator` string, nullable
          - `pickup_city` string, nullable
          - `pickup_address` string, nullable
          - `pickup_datetime` string, date-time, required
          - `dropoff_city` string, nullable
          - `dropoff_address` string, nullable
          - `dropoff_datetime` string, date-time, nullable
          - `duration_minutes` integer
          - `total_price` number, nullable
          - `currency` string
          - `passenger_names` string[]
          - `__index` integer, required
          - `__tool_call_id` string, required
          - `message_id` string, nullable
          - `confirmation_number` string, nullable
          - `is_booked` boolean
          - `is_user_import` boolean
      - CarRentalBookingItem
        - `id` string, required
        - `event_date` string, nullable, required
        - `created_at` string, required
        - `confirmation_number` string, nullable, required
        - `status` 'active' | 'cancelled'
        - `gmail_link` string, nullable
        - `import_kind` 'email' | 'image' | 'text', nullable
        - `import_link` string, nullable
        - `import_sources` ImportSource[]
          - `kind` 'email' | 'image' | 'text', required
          - `link` string, nullable
          - `created_at` string, date-time, required
        - `source` 'email_import' | 'first_party'
        - `trip_id` string, nullable
        - `trip_title` string, nullable
        - `review` BookingReview
          - `question` 'which_trip' | 'is_this_yours', required
          - `travelers` string[]
          - `nudge` boolean
        - `booking_type` 'car_rental'
        - `card_data` CarRentalCardData, required — Car rental card data for the frontend CarRentalCard component.
          - `vendor` string, required
          - `pickup_location` string, nullable
          - `pickup_city` string, nullable
          - `pickup_datetime` string, date-time, required
          - `dropoff_location` string, nullable
          - `dropoff_city` string, nullable
          - `dropoff_datetime` string, date-time, nullable
          - `vehicle_class` string, nullable
          - `driver_name` string, nullable
          - `total_price` number, nullable
          - `currency` string
          - `__index` integer, required
          - `__tool_call_id` string, required
          - `message_id` string, nullable
          - `confirmation_number` string, nullable
          - `is_booked` boolean
          - `is_user_import` boolean
      - EventBookingItem
        - `id` string, required
        - `event_date` string, nullable, required
        - `created_at` string, required
        - `confirmation_number` string, nullable, required
        - `status` 'active' | 'cancelled'
        - `gmail_link` string, nullable
        - `import_kind` 'email' | 'image' | 'text', nullable
        - `import_link` string, nullable
        - `import_sources` ImportSource[]
          - `kind` 'email' | 'image' | 'text', required
          - `link` string, nullable
          - `created_at` string, date-time, required
        - `source` 'email_import' | 'first_party'
        - `trip_id` string, nullable
        - `trip_title` string, nullable
        - `review` BookingReview
          - `question` 'which_trip' | 'is_this_yours', required
          - `travelers` string[]
          - `nudge` boolean
        - `booking_type` 'event'
        - `card_data` AttractionDisplayData, required — Pre-formatted attraction data for AttractionCard component.
          - `from_email` boolean
          - `gmail_link` string, nullable
          - `import_kind` 'email' | 'image' | 'text', nullable
          - `import_link` string, nullable
          - `import_sources` ImportSource[]
            - `kind` 'email' | 'image' | 'text', required
            - `link` string, nullable
            - `created_at` string, date-time, required
          - `id` string, required
          - `name` string, required
          - `place_id` string, nullable
          - `latitude` number, nullable
          - `longitude` number, nullable
          - `thumbnail` string, nullable
          - `thumbnail_thumbhash` string, nullable
          - `rating` number, nullable
          - `num_reviews` integer, nullable
          - `category` string, nullable
          - `address` string, nullable
          - `city` string, nullable
          - `state` string, nullable
          - `country` string, nullable
          - `source_reference` SourceReference — Reference to a cached tool result for tracking itinerary item sources. ``source`` distinguishes provenance: ``api`` (an AI/tool search result), ``user_import`` (parsed from the user's email — renders a "From email" badge and the imageless cost-breakdown card), ``user_manual`` (added by hand via the "Add stay" form — a normal image-carrying card, no badge), and ``user_booking`` (WE sold it — a first-party reservation taken through our own checkout; see api/services/hotel_booking_stay.py). ``user_booking`` is deliberately NOT ``user_import``: the item did not come from the user's inbox, and a "From email" badge on a booking we took money for would be a lie. Frontends branch only on ``user_import``, so the new value falls through to the ordinary card.
            - `tool_call_id` string, required
            - `result_index` integer, required
            - `source` 'api' | 'user_import' | 'user_manual' | 'user_booking'
          - `activity_details` object, nullable
          - `activity_type` string, nullable
          - `start_datetime` string, nullable
          - `end_datetime` string, nullable
          - `venue_name` string, nullable
          - `seat_info` string, nullable
          - `quantity` integer, nullable
          - `booking_source` string, nullable
          - `confirmation_number` string, nullable
          - `total_price` number, nullable
          - `currency` string, nullable
          - `is_booked` boolean

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