> ## Documentation Index > Fetch the complete documentation index at: https://docs.gojinko.com/llms.txt > Use this file to discover all available pages before exploring further. # flight-schedule > Flights observed between two places on exact dates (no price) 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. ## OpenAPI ````yaml api-reference/public-api.yaml POST /v1/flight_schedule openapi: 3.0.0 info: title: Jinko Public API version: 0.26.0 description: >- Curated public REST surface for Jinko. Authenticated with jnk_ API keys. See https://docs.gojinko.com for guides. ### Per-end-user attribution On booking calls you may send an optional `X-End-User-Id` request header to attribute the booking to one of your own end users (for per-end-user attribution and rate-limiting). The value is an **opaque, tenant-scoped** identifier that you choose — not a Jinko account id. Omit it to book as the tenant. WorkOS-shaped values (prefixed `user_` or `org_`) are rejected. servers: - url: https://api.gojinko.com description: Production - url: https://api.sandbox.gojinko.com description: Sandbox security: [] paths: /v1/flight_schedule: post: tags: - Discovery summary: Flights observed between two places on exact dates (no price) description: >- 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. requestBody: content: application/json: schema: $ref: '#/components/schemas/FlightScheduleRequest' responses: '200': description: Observed trips; `trips` is empty when nothing matches content: application/json: schema: $ref: '#/components/schemas/FlightScheduleResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: BAD_REQUEST message: Malformed JSON in request body. doc_url: https://docs.gojinko.com/concepts/errors '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: AUTH_REQUIRED message: Invalid or expired API key. doc_url: https://docs.gojinko.com/authentication/api-keys '402': description: Payment required — organization balance exhausted content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: PAYMENT_REQUIRED message: >- Insufficient balance — this call costs $0.0150 and your organization has $0.0000 available. Top up at https://dashboard.gojinko.com/developers/billing/topup doc_url: https://docs.gojinko.com/concepts/errors '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: NOT_FOUND message: Resource not found. doc_url: https://docs.gojinko.com/concepts/errors '409': description: The operation conflicts with the current state of the resource content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: CONFLICT message: >- The operation conflicts with the current state of the resource. doc_url: https://docs.gojinko.com/concepts/errors '410': description: The resource this request names no longer exists content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: GONE message: The resource no longer exists. doc_url: https://docs.gojinko.com/concepts/errors '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: BAD_REQUEST message: A required field is missing or invalid. doc_url: https://docs.gojinko.com/concepts/errors '429': description: Rate limit or quota exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: RATE_LIMITED message: Rate limit or quota exceeded. doc_url: https://docs.gojinko.com/concepts/errors '502': description: The travel provider rejected the request, or an upstream call failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UPSTREAM_REJECTED message: The upstream service rejected the request. doc_url: https://docs.gojinko.com/concepts/errors '503': description: No travel provider can serve the request right now headers: Retry-After: description: >- Seconds to wait before retrying, forwarded verbatim from the upstream service. Absent when the upstream named no interval. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UPSTREAM_UNAVAILABLE message: >- The upstream service is temporarily unavailable. Please retry later. doc_url: https://docs.gojinko.com/concepts/errors '504': description: The travel provider did not answer in time content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UPSTREAM_TIMEOUT message: The upstream service did not respond in time. doc_url: https://docs.gojinko.com/concepts/errors security: - ApiKeyAuth: [] - BearerAuth: [] components: schemas: FlightScheduleRequest: type: object properties: origin: type: string pattern: ^[A-Za-z]{3}$ example: BOS destination: type: string pattern: ^[A-Za-z]{3}$ example: NCE origin_type: type: string enum: - city - airport description: >- How to read the code: `city` (default) expands a city code to all of its airports; `airport` restricts to that one airport. destination_type: type: string enum: - city - airport description: >- How to read the code: `city` (default) expands a city code to all of its airports; `airport` restricts to that one airport. trip_type: type: string enum: - oneway - roundtrip description: >- `oneway` returns trips observed as one-way offers and takes no `return_date`. `roundtrip` returns observed outbound + inbound pairings and requires `return_date`. example: roundtrip departure_date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: Local departure day of the outbound journey. example: '2026-10-11' return_date: type: string pattern: ^\d{4}-\d{2}-\d{2}$ description: >- Local departure day of the inbound journey. Required when `trip_type` is `roundtrip`; not accepted when it is `oneway`. example: '2026-10-18' cabin_class: type: string enum: - economy - premium_economy - business - first description: >- 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: type: integer minimum: 0 maximum: 3 description: Most stops allowed in EACH direction. Omit for no bound. example: 1 limit: type: integer minimum: 1 maximum: 200 description: Page size. Defaults to 50. example: 50 page_token: type: string minLength: 1 description: >- `pagination.next_page_token` of the previous page. Send it with the same request fields. intent: $ref: '#/components/schemas/IntentInput' required: - origin - destination - trip_type - departure_date example: origin: BOS destination: NCE trip_type: roundtrip departure_date: '2026-10-11' return_date: '2026-10-18' max_stops: 1 FlightScheduleResponse: type: object properties: trips: type: array items: $ref: '#/components/schemas/ScheduleTrip' description: The page of observed trips. Empty when nothing matches. total: type: integer description: >- Trips matching the whole request across all pages. A lower bound when `truncated` is true. example: 116 truncated: type: boolean description: >- 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: type: object properties: next_page_token: type: string description: >- 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. required: - next_page_token required: - trips - total - truncated - pagination ErrorResponse: type: object properties: error: type: object properties: code: type: string enum: - credential_format_invalid - payment_type_not_enabled - payment_credential_invalid - trip_owned_by_other_payment - idempotency_key_reused - attempt_in_progress - quote_expired - attempt_terminal - temporarily_unavailable - AUTH_REQUIRED - PAYMENT_REQUIRED - RATE_LIMITED - BAD_REQUEST - FORBIDDEN - NOT_FOUND - CONFLICT - GONE - QUOTE_EXPIRED - TRIP_EXPIRED - TRIP_STATE_CONFLICT - OFFER_EXPIRED - OFFER_UNAVAILABLE - MISSING_CUSTOMER_DETAILS - INVALID_PHONE_NUMBER - CURRENCY_UNSUPPORTED - HOTEL_NAME_LOW_CONFIDENCE - DESTINATION_LOW_CONFIDENCE - UPSTREAM_REJECTED - UPSTREAM_UNAVAILABLE - UPSTREAM_TIMEOUT - UPSTREAM_ERROR - INTERNAL description: >- What went wrong, as a stable machine-readable code. This is a closed set — branch on it rather than on `message`, which is prose and may change. New codes arrive in a minor version, so treat an unknown one as its HTTP status. A code can also stop being emitted: it leaves this set in a minor version, named in the changelog, and a branch you wrote for it goes unreached rather than wrong. example: BAD_REQUEST message: type: string doc_url: type: string field: type: string description: >- On a 400 `BAD_REQUEST` that names one refused input: the path of that field in your request, e.g. `selections[1].quantity` for the second selection of a `select_ancillaries` call. Absent when the refusal names no single field. example: selections[1].quantity required: - code - message required: - error IntentInput: type: object properties: user_intent: type: string nullable: true description: >- The user's natural-language intent: the Alpic PII-stripped paraphrase when available, else a best-effort fallback to the client-provided NL query. example: find a cheap flight to Tokyo ScheduleTrip: type: object properties: trip_type: type: string enum: - oneway - roundtrip example: roundtrip cabin_class: type: string enum: - economy - premium_economy - business - first description: The highest cabin over all segments of the trip. validating_carrier: type: string example: AF last_seen: type: string description: >- When a fare search last observed this trip (UTC). It is NOT a statement that the trip can be booked today. example: '2026-09-30T04:12:09Z' slices: type: array items: $ref: '#/components/schemas/ScheduleSlice' description: >- One slice for a one-way trip; outbound then inbound for a round trip. required: - trip_type - validating_carrier - last_seen - slices ScheduleSlice: type: object properties: origin: type: string example: BOS destination: type: string example: NCE stops: type: integer description: Segment count minus one. example: 1 segments: type: array items: $ref: '#/components/schemas/ScheduleSegment' required: - origin - destination - stops - segments ScheduleSegment: type: object properties: marketing_carrier: type: string example: AF marketing_carrier_info: $ref: '#/components/schemas/ScheduleCarrier' operating_carrier: type: string example: DL operating_carrier_info: $ref: '#/components/schemas/ScheduleCarrier' flight_number: type: string example: '333' cabin_class: type: string enum: - economy - premium_economy - business - first description: This segment’s cabin in this trip. depart: $ref: '#/components/schemas/ScheduleEndpoint' arrive: $ref: '#/components/schemas/ScheduleEndpoint' required: - marketing_carrier - flight_number - depart - arrive ScheduleCarrier: type: object properties: code: type: string example: AF name: type: string example: Air France ScheduleEndpoint: type: object properties: airport: type: string example: BOS city_code: type: string example: BOS city_name: type: string example: Boston time_local: type: string description: >- 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. example: 2026-10-11T18:25 required: - airport - time_local securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key BearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.