Polyflight flights

Required scope: polyflight:read.

GET /api/operator/polyflight/flights
GET /api/operator/polyflight/flights/{flightIdOrCode}
GET /api/operator/polyflight/flights/export
Authorization: Bearer {operator_api_key_or_staff_session}

A flight appears only when the authenticated operator owns at least one operator-wallet ticket in it. Counts and amounts describe that operator's cohort, not all participation in the global flight. A cross-operator flight identifier returns 404 POLYFLIGHT_FLIGHT_NOT_FOUND. Responses use Cache-Control: private, no-store.

List and export filters

ISO date intervals are half-open. Local calendar-day bounds account for daylight saving and also constrain the query when combined with ISO bounds. Invalid calendar dates or reversed ranges return 400; the client cannot override the authenticated operator's timezone. Invalid/repeated game values return 400 INVALID_GAME. Unknown status values are accepted syntactically but match no flights. The detail identifier accepts a flight UUID or a 3–64 character alphanumeric/hyphen flight code; detail reads use the identifier and operator ownership, not list query filters.

curl -sS -G \
  -H "Authorization: Bearer ${OPERATOR_API_KEY}" \
  --data-urlencode "status=landed,void" \
  --data-urlencode "date_from=2026-08-01T00:00:00Z" \
  --data-urlencode "date_to=2026-09-01T00:00:00Z" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=25" \
  "https://your-beacon-origin.example.com/api/operator/polyflight/flights"

Representative list response

{
  "items": [
    {
      "flightId": "018f6f8a-0c47-7af3-8ac2-6c5d9f166d85",
      "flightCode": "PF-20260817-1200-A",
      "game": "polyflight",
      "status": "landed",
      "opensAt": "2026-08-17T11:55:00.000Z",
      "locksAt": "2026-08-17T11:59:30.000Z",
      "landsAt": "2026-08-17T12:00:00.000Z",
      "revealedAt": "2026-08-17T12:00:03.000Z",
      "operatorId": 42,
      "ticketCount": 4,
      "userCount": 3,
      "stakeMinor": "40000",
      "feeMinor": "2000",
      "netStakeMinor": "38000",
      "potentialPayoutMinor": "152000",
      "wonCount": 1,
      "lostCount": 3,
      "refundCount": 0,
      "unpaidLiabilityMinor": "38000"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 25,
  "summary": {
    "flightCount": 1,
    "ticketCount": 4,
    "userCount": 3,
    "stakeMinor": "40000",
    "feeMinor": "2000",
    "unpaidLiabilityMinor": "38000",
    "currencyCode": "IDR"
  }
}

summary covers all matching operator-owned tickets on the filtered flights, independent of pagination. Users are distinct across the whole result, not the sum of per-flight user counts. Money remains exact integer decimal strings. When no flights match, the list returns items: [], total: 0, and zero summary values. A page beyond the last match retains the matching total and summary. The detail route returns one item without the page envelope.

game identifies Classic or Pro on every row. unpaidLiabilityMinor covers currently unpaid ticket-linked obligations, not unadmitted-purchase compensation; inspect overview and wallet operations for compensation. Zero-amount loss acknowledgements add no monetary liability. feeMinor is the tickets' included quoted fee, not the net fee entitlement after cancellation reversals or the operator's commercial allocation.

Export

Export applies the same ISO/local date, status, and search filters to all matching rows; page and page_size do not limit the export. CSV is the default:

curl -sS -G \
  -H "Authorization: Bearer ${OPERATOR_API_KEY}" \
  --data-urlencode "status=landed" \
  "https://your-beacon-origin.example.com/api/operator/polyflight/flights/export" \
  --output polyflight-flights.csv

Add format=json for the canonical JSON list envelope. CSV is empty when no rows match.

In the dashboard, open Polyflight → Flights to browse the operator cohort. Both date inputs default to the last 30 calendar days including today in the operator's timezone; Reset restores that range using the current local day. Dates filter flight opening time. Change dates or status, then choose Apply filters; Export all filtered uses only the applied filters. Use Tickets to identify each owned ticket behind a cohort total and Settlement reports for finalized monthly allocation.

The dashboard combines both games and has no game or flight-code search control on this page. Use the API's game and search filters when a support case requires that narrower export.

Metric cards show all-filtered flight/ticket/distinct-user counts, stake, included fees, and currently outstanding liability. The bounded table has sticky headers and a sticky Current page SUM footer for stake, fees, and outstanding liability. Table amount cells are plain integer digits without currency suffixes or grouping separators, with IDR stated in the headers; canonical CSV amount fields likewise remain raw numeric values. Cards and SUMs show loading/unavailable states instead of stale amounts or fabricated zeros after failed requests. A successful empty result shows genuine zero totals.

Playground: /api-playground/polyflight?request=polyflight-flights.