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

The date interval is half-open. 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.

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",
      "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
}

When no flights match, the list returns items: [] and total: 0. A page beyond the last match has empty items but retains the matching total. The detail route returns one item in the same shape without the page envelope.

Export

Export applies date_from, date_to, status, and search 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 and use Export all filtered for filters the page exposes. For exact scheduled, gate_closed, or void filtering, use the request above or API Playground; those API statuses are not all available in the current dashboard selector. Use Tickets to identify each owned ticket behind a cohort total and Settlement reports for finalized monthly allocation.

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