---
title: "Read qualified Beta predictions"
method: GET
path: "/v1/predictions"
tags: ["Predictions"]
---

# Read qualified Beta predictions

`GET /v1/predictions`

## Request

- Base URL: `https://sweetsaverfare.com`
- URL: `https://sweetsaverfare.com/v1/predictions`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://sweetsaverfare.com/oauth/auth`, token URL `https://sweetsaverfare.com/oauth/token`, scopes: `predictions:read`)

Returns stored qualified Beta fare or vehicle-space predictions when the account is entitled and reliable prediction evidence is available.

## Query parameters

- `sailing_instance_id` string[], required
- `profile_id` 'ADULT_NO_VEHICLE' | 'ADULT_STANDARD_VEHICLE' | 'ADULT_OVERHEIGHT_VEHICLE', required
- `target` 'LOWER_SAVER_24H' | 'LOWER_SAVER_7D' | 'DECREASE_BEFORE_SAILING' | 'VEHICLE_SPACE_AVAILABILITY'

## Response `200`

Stored beta fare and vehicle prediction

- object
  - `plan` 'frequent_traveller' | 'connected_traveller', required
  - `predictions` PredictionSnapshot[], required
    - union
      - object
        - `sailing_instance_id` string, uuid, required
        - `route_id` 'TSA_SWB' | 'SWB_TSA' | 'TSA_DUK' | 'DUK_TSA' | 'TSA_NAN' | 'HSB_NAN' | 'NAN_HSB' | 'SWB_FUL' | 'FUL_SWB' | 'HSB_LNG' | 'LNG_HSB' | 'ERL_SLT' | 'SLT_ERL' | 'CMX_PWR' | 'PWR_CMX', required
        - `profile_id` 'ADULT_NO_VEHICLE' | 'ADULT_STANDARD_VEHICLE' | 'ADULT_OVERHEIGHT_VEHICLE', required
        - `target` 'LOWER_SAVER_24H' | 'LOWER_SAVER_7D' | 'DECREASE_BEFORE_SAILING' | 'VEHICLE_SPACE_AVAILABILITY', required
        - `feature_cutoff` string, date-time, required
        - `observed_at` string, date-time, required
        - `stale_after` string, date-time, required
        - `freshness_state` 'fresh', required
        - `source_observation_id` string, uuid, required
        - `source_status` 'ok' | 'missing' | 'provider_queue_active' | 'session_expired' | 'blocked' | 'unknown', required
        - `data_source` 'demo' | 'fake_worker' | 'fixture' | 'live_provider' | 'schedule_reference', required
        - `parser_version` string, required
        - `observation_trace_id` string, nullable, required
        - `fixture_sha` string, nullable, required
        - `observation_outcome` 'verified' | 'partial' | 'unavailable' | 'failed', required
        - `outcome_reason` string, nullable, required
        - `horizon_hours` integer, required
        - `output_kind` 'probability', required
        - `release_stage` 'beta', required
        - `evidence_source` 'fare_observation' | 'current_conditions', required
        - `evidence_window_start` string, date-time, required
        - `evidence_window_end` string, date-time, required
        - `probability` number, nullable, required
        - `interval_lower` number, nullable, required
        - `interval_upper` number, nullable, required
        - `estimate_percent` number, nullable
        - `lower_percent` number, nullable
        - `upper_percent` number, nullable
        - `timeline_points` object[], nullable
          - `hours_before_departure` 12 | 6 | 3 | 1, required
          - `estimate_percent` number, required
          - `lower_percent` number, required
          - `upper_percent` number, required
        - `checkpoint_at` string, date-time, nullable, required
        - `checkpoint_kind` 'preceding_sailing_departure' | 'two_hours_before_departure' | 'null', nullable, required
        - `first_full_estimate_at` string, date-time, nullable, required
        - `first_full_lower_at` string, date-time, nullable, required
        - `first_full_upper_at` string, date-time, nullable, required
      - object
        - `sailing_instance_id` string, uuid, required
        - `route_id` 'TSA_SWB' | 'SWB_TSA' | 'TSA_DUK' | 'DUK_TSA' | 'TSA_NAN' | 'HSB_NAN' | 'NAN_HSB' | 'SWB_FUL' | 'FUL_SWB' | 'HSB_LNG' | 'LNG_HSB' | 'ERL_SLT' | 'SLT_ERL' | 'CMX_PWR' | 'PWR_CMX', required
        - `profile_id` 'ADULT_NO_VEHICLE' | 'ADULT_STANDARD_VEHICLE' | 'ADULT_OVERHEIGHT_VEHICLE', required
        - `target` 'LOWER_SAVER_24H' | 'LOWER_SAVER_7D' | 'DECREASE_BEFORE_SAILING' | 'VEHICLE_SPACE_AVAILABILITY', required
        - `feature_cutoff` string, date-time, required
        - `observed_at` string, date-time, required
        - `stale_after` string, date-time, required
        - `freshness_state` 'fresh', required
        - `source_observation_id` string, uuid, required
        - `source_status` 'ok' | 'missing' | 'provider_queue_active' | 'session_expired' | 'blocked' | 'unknown', required
        - `data_source` 'demo' | 'fake_worker' | 'fixture' | 'live_provider' | 'schedule_reference', required
        - `parser_version` string, required
        - `observation_trace_id` string, nullable, required
        - `fixture_sha` string, nullable, required
        - `observation_outcome` 'verified' | 'partial' | 'unavailable' | 'failed', required
        - `outcome_reason` string, nullable, required
        - `horizon_hours` integer, required
        - `output_kind` 'percentage_range', required
        - `release_stage` 'beta', required
        - `evidence_source` 'fare_observation' | 'current_conditions', required
        - `evidence_window_start` string, date-time, required
        - `evidence_window_end` string, date-time, required
        - `probability` number, nullable
        - `interval_lower` number, nullable
        - `interval_upper` number, nullable
        - `estimate_percent` number, nullable, required
        - `lower_percent` number, nullable, required
        - `upper_percent` number, nullable, required
        - `timeline_points` object[], nullable
          - `hours_before_departure` 12 | 6 | 3 | 1, required
          - `estimate_percent` number, required
          - `lower_percent` number, required
          - `upper_percent` number, required
        - `checkpoint_at` string, date-time, nullable, required
        - `checkpoint_kind` 'preceding_sailing_departure' | 'two_hours_before_departure' | 'null', nullable, required
        - `first_full_estimate_at` string, date-time, nullable, required
        - `first_full_lower_at` string, date-time, nullable, required
        - `first_full_upper_at` string, date-time, nullable, required
      - object
        - `sailing_instance_id` string, uuid, required
        - `route_id` 'TSA_SWB' | 'SWB_TSA' | 'TSA_DUK' | 'DUK_TSA' | 'TSA_NAN' | 'HSB_NAN' | 'NAN_HSB' | 'SWB_FUL' | 'FUL_SWB' | 'HSB_LNG' | 'LNG_HSB' | 'ERL_SLT' | 'SLT_ERL' | 'CMX_PWR' | 'PWR_CMX', required
        - `profile_id` 'ADULT_NO_VEHICLE' | 'ADULT_STANDARD_VEHICLE' | 'ADULT_OVERHEIGHT_VEHICLE', required
        - `target` 'LOWER_SAVER_24H' | 'LOWER_SAVER_7D' | 'DECREASE_BEFORE_SAILING' | 'VEHICLE_SPACE_AVAILABILITY', required
        - `feature_cutoff` string, date-time, required
        - `observed_at` string, date-time, required
        - `stale_after` string, date-time, required
        - `freshness_state` 'fresh', required
        - `source_observation_id` string, uuid, required
        - `source_status` 'ok' | 'missing' | 'provider_queue_active' | 'session_expired' | 'blocked' | 'unknown', required
        - `data_source` 'demo' | 'fake_worker' | 'fixture' | 'live_provider' | 'schedule_reference', required
        - `parser_version` string, required
        - `observation_trace_id` string, nullable, required
        - `fixture_sha` string, nullable, required
        - `observation_outcome` 'verified' | 'partial' | 'unavailable' | 'failed', required
        - `outcome_reason` string, nullable, required
        - `horizon_hours` integer, required
        - `output_kind` 'percentage_timeline', required
        - `release_stage` 'beta', required
        - `evidence_source` 'fare_observation' | 'current_conditions', required
        - `evidence_window_start` string, date-time, required
        - `evidence_window_end` string, date-time, required
        - `probability` number, nullable
        - `interval_lower` number, nullable
        - `interval_upper` number, nullable
        - `estimate_percent` number, nullable
        - `lower_percent` number, nullable
        - `upper_percent` number, nullable
        - `timeline_points` object[], nullable, required
          - `hours_before_departure` 12 | 6 | 3 | 1, required
          - `estimate_percent` number, required
          - `lower_percent` number, required
          - `upper_percent` number, required
        - `checkpoint_at` string, date-time, nullable, required
        - `checkpoint_kind` 'preceding_sailing_departure' | 'two_hours_before_departure' | 'null', nullable, required
        - `first_full_estimate_at` string, date-time, nullable, required
        - `first_full_lower_at` string, date-time, nullable, required
        - `first_full_upper_at` string, date-time, nullable, required
      - object
        - `sailing_instance_id` string, uuid, required
        - `route_id` 'TSA_SWB' | 'SWB_TSA' | 'TSA_DUK' | 'DUK_TSA' | 'TSA_NAN' | 'HSB_NAN' | 'NAN_HSB' | 'SWB_FUL' | 'FUL_SWB' | 'HSB_LNG' | 'LNG_HSB' | 'ERL_SLT' | 'SLT_ERL' | 'CMX_PWR' | 'PWR_CMX', required
        - `profile_id` 'ADULT_NO_VEHICLE' | 'ADULT_STANDARD_VEHICLE' | 'ADULT_OVERHEIGHT_VEHICLE', required
        - `target` 'LOWER_SAVER_24H' | 'LOWER_SAVER_7D' | 'DECREASE_BEFORE_SAILING' | 'VEHICLE_SPACE_AVAILABILITY', required
        - `feature_cutoff` string, date-time, required
        - `observed_at` string, date-time, required
        - `stale_after` string, date-time, required
        - `freshness_state` 'fresh', required
        - `source_observation_id` string, uuid, required
        - `source_status` 'ok' | 'missing' | 'provider_queue_active' | 'session_expired' | 'blocked' | 'unknown', required
        - `data_source` 'demo' | 'fake_worker' | 'fixture' | 'live_provider' | 'schedule_reference', required
        - `parser_version` string, required
        - `observation_trace_id` string, nullable, required
        - `fixture_sha` string, nullable, required
        - `observation_outcome` 'verified' | 'partial' | 'unavailable' | 'failed', required
        - `outcome_reason` string, nullable, required
        - `horizon_hours` integer, required
        - `output_kind` 'vehicle_availability', required
        - `release_stage` 'beta', required
        - `evidence_source` 'fare_observation' | 'current_conditions', required
        - `evidence_window_start` string, date-time, required
        - `evidence_window_end` string, date-time, required
        - `probability` number, nullable, required
        - `interval_lower` number, nullable, required
        - `interval_upper` number, nullable, required
        - `estimate_percent` number, nullable
        - `lower_percent` number, nullable
        - `upper_percent` number, nullable
        - `timeline_points` object[], nullable
          - `hours_before_departure` 12 | 6 | 3 | 1, required
          - `estimate_percent` number, required
          - `lower_percent` number, required
          - `upper_percent` number, required
        - `checkpoint_at` string, date-time, nullable, required
        - `checkpoint_kind` 'preceding_sailing_departure' | 'two_hours_before_departure' | 'null', nullable, required
        - `first_full_estimate_at` string, date-time, nullable, required
        - `first_full_lower_at` string, date-time, nullable, required
        - `first_full_upper_at` string, date-time, nullable, required
  - `disclaimer` string, required

## Other responses

- `400`: Invalid request
- `401`: Authentication required
- `403`: Frequent or Connected entitlement required
- `429`: Request rate limit exceeded
- `500`: Internal server error
- `503`: Prediction service unavailable

---

[API](https://skmtc.dev/sweetsaverfare/apis/sweet-saver-fare-public-api.md) · [All operations](https://skmtc.dev/sweetsaverfare/apis/sweet-saver-fare-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sweetsaverfare/apis/sweet-saver-fare-public-api/revisions/102cb8af7798?raw)