---
title: "Flights observed between two places on exact dates (no price)"
method: POST
path: "/v1/flight_schedule"
tags: ["Discovery"]
---

# Flights observed between two places on exact dates (no price)

`POST /v1/flight_schedule`

## Request

- Base URL: `https://api.gojinko.com`
- URL: `https://api.gojinko.com/v1/flight_schedule`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Returns the trips the flight catalog has observed for one origin, one destination and an exact date pair. `trip_type` says which kind: `oneway` (no `return_date`) or `roundtrip` (`return_date` required); a round trip is an outbound + inbound pairing that was actually observed together, never a combination built from two one-ways. The answer carries no price, and `last_seen` is when a fare search last observed the trip — not a statement that it can be booked. Results are paged: send `pagination.next_page_token` back as `page_token` until it is empty.

## Request body

- FlightScheduleRequest
  - `origin` string, required
  - `destination` string, required
  - `origin_type` 'city' | 'airport': How to read the code: `city` searches every airport of the city, `airport` only that one airport. Omit it and the platform applies one rule: a code that names a multi-airport city is searched as the city; every other code is searched as the airport. Untyped NYC, LON or PAR is the city; untyped JFK, LHR or CDG is the airport; and untyped LAX, MIA or LAS — codes a city shares with its main airport — is the CITY, so results can land at any airport of that city. If the user named the airport, send `airport`; if they named the city, omit the field.
  - `destination_type` 'city' | 'airport': How to read the code: `city` searches every airport of the city, `airport` only that one airport. Omit it and the platform applies one rule: a code that names a multi-airport city is searched as the city; every other code is searched as the airport. Untyped NYC, LON or PAR is the city; untyped JFK, LHR or CDG is the airport; and untyped LAX, MIA or LAS — codes a city shares with its main airport — is the CITY, so results can land at any airport of that city. If the user named the airport, send `airport`; if they named the city, omit the field.
  - `trip_type` 'oneway' | 'roundtrip', required: `oneway` returns trips observed as one-way offers and takes no `return_date`. `roundtrip` returns observed outbound + inbound pairings and requires `return_date`.
  - `departure_date` string, required: Local departure day of the outbound journey.
  - `return_date` string: Local departure day of the inbound journey. Required when `trip_type` is `roundtrip`; not accepted when it is `oneway`.
  - `cabin_class` 'economy' | 'premium_economy' | 'business' | 'first': Filters on the trip’s cabin (the highest over its segments). Omit for all cabins — unlike flight search there is no economy default.
  - `max_stops` integer: Most stops allowed in EACH direction. Omit for no bound.
  - `limit` integer: Page size. Defaults to 50.
  - `page_token` string: `pagination.next_page_token` of the previous page. Send it with the same request fields.
  - `intent` IntentInput
    - `user_intent` string, nullable: The user's natural-language intent: the Alpic PII-stripped paraphrase when available, else a best-effort fallback to the client-provided NL query.

## Response `200`

Observed trips; `trips` is empty when nothing matches

- FlightScheduleResponse
  - `trips` ScheduleTrip[], required: The page of observed trips. Empty when nothing matches.
    - `trip_type` 'oneway' | 'roundtrip', required
    - `cabin_class` 'economy' | 'premium_economy' | 'business' | 'first': The highest cabin over all segments of the trip.
    - `validating_carrier` string, required
    - `last_seen` string, required: When a fare search last observed this trip (UTC). It is NOT a statement that the trip can be booked today.
    - `slices` ScheduleSlice[], required: One slice for a one-way trip; outbound then inbound for a round trip.
      - `origin` string, required
      - `destination` string, required
      - `stops` integer, required: Segment count minus one.
      - `segments` ScheduleSegment[], required
        - `marketing_carrier` string, required
        - `marketing_carrier_info` ScheduleCarrier
          - `code` string
          - `name` string
        - `operating_carrier` string
        - `operating_carrier_info` ScheduleCarrier
          - `code` string
          - `name` string
        - `flight_number` string, required
        - `cabin_class` 'economy' | 'premium_economy' | 'business' | 'first': This segment’s cabin in this trip.
        - `depart` ScheduleEndpoint, required
          - `airport` string, required
          - `city_code` string
          - `city_name` string
          - `time_local` string, required: Local date and time at the airport, `YYYY-MM-DDTHH:MM`, with NO UTC offset. It is not an instant: it cannot be compared across timezones, and parsing it as UTC is wrong by the airport’s offset.
        - `arrive` ScheduleEndpoint, required
          - `airport` string, required
          - `city_code` string
          - `city_name` string
          - `time_local` string, required: Local date and time at the airport, `YYYY-MM-DDTHH:MM`, with NO UTC offset. It is not an instant: it cannot be compared across timezones, and parsing it as UTC is wrong by the airport’s offset.
  - `total` integer, required: Trips matching the whole request across all pages. A lower bound when `truncated` is true.
  - `truncated` boolean, required: True when an airport pair held more trips than one catalog read covers. Narrow by `cabin_class`, `max_stops` or a single airport to see the rest.
  - `pagination` object, required
    - `next_page_token` string, required: Send back as `page_token` for the next page; empty on the last page. A page may hold fewer trips than `limit` — only an empty token ends the result.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `402`: Payment required — organization balance exhausted
- `404`: Resource not found
- `409`: The operation conflicts with the current state of the resource
- `410`: The resource this request names no longer exists
- `422`: Validation error
- `429`: Rate limit or quota exceeded
- `502`: The travel provider rejected the request, or an upstream call failed
- `503`: No travel provider can serve the request right now
- `504`: The travel provider did not answer in time

---

[API](https://skmtc.dev/gojinko/apis/jinko-public-api.md) - [All operations](https://skmtc.dev/gojinko/apis/jinko-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gojinko/apis/jinko-public-api/revisions/ac5046767e4c?raw)