> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dev.gojinko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# find-dates

> Best date options for a route — up to ten cheapest itineraries, one per date-pair, spread across the month

Answers "when should I fly?" for a known route. Takes the same inputs as Flight Calendar but returns up to ten cheapest itineraries, one per (departure, return) date-pair, spread across the requested departure window, so the user gets a diverse shortlist rather than ten near-adjacent cheapest days. Cache-backed; no live pricing. Each result includes an offer token you can pass into a live price check or directly into a trip.


## OpenAPI

````yaml api-reference/public-api.yaml POST /v1/find_dates
openapi: 3.0.0
info:
  title: Jinko Public API
  version: 0.1.0
  description: >-
    Curated public REST surface for Jinko. Authenticated with jnk_ API keys. See
    https://docs.gojinko.com for guides.
servers: []
security: []
paths:
  /v1/find_dates:
    post:
      tags:
        - Discovery
      summary: >-
        Best date options for a route — up to ten cheapest itineraries, one per
        date-pair, spread across the month
      description: >-
        Takes the same request as flight_calendar and returns up to ten cheapest
        itineraries — one per (departure, return) date-pair — spread across the
        requested departure window, so you see a diverse set of date options
        rather than ten near-adjacent cheapest days. Cache-backed; never
        live-prices.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlightDiscoveryRequest'
      responses:
        '200':
          description: Best date options (one itinerary per date-pair)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightCalendarResponse'
        '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/api-reference/authentication
        '422':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: BAD_REQUEST
                  message: >-
                    origins: origins is required; trip_type: trip_type is
                    required
                  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: Upstream service error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UPSTREAM_ERROR
                  message: Upstream travel provider returned an error. Please retry.
                  doc_url: https://docs.gojinko.com/concepts/errors
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
components:
  schemas:
    FlightDiscoveryRequest:
      type: object
      properties:
        origins:
          type: array
          items:
            type: string
          minItems: 1
          example:
            - NYC
        destinations:
          type: array
          items:
            type: string
          example:
            - PAR
        origin_type:
          type: string
          enum:
            - city
            - airport
          default: city
        destination_type:
          type: string
          enum:
            - city
            - airport
          default: city
        departure_dates:
          type: array
          items:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
          example:
            - '2026-07-15'
        departure_date_ranges:
          type: array
          items:
            $ref: '#/components/schemas/DateRange'
        return_dates:
          type: array
          items:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2}$
          example:
            - '2026-07-22'
        return_date_ranges:
          type: array
          items:
            $ref: '#/components/schemas/DateRange'
        stay_days:
          type: integer
          minimum: 0
          exclusiveMinimum: true
          example: 7
        stay_days_range:
          type: object
          properties:
            min:
              type: integer
            max:
              type: integer
          required:
            - min
            - max
        trip_type:
          type: string
          enum:
            - oneway
            - roundtrip
          example: roundtrip
        cabin_class:
          type: string
          enum:
            - economy
            - premium_economy
            - business
            - first
          example: economy
        direct_only:
          type: boolean
          example: false
        adults:
          type: integer
          minimum: 0
          example: 1
        children:
          type: integer
          minimum: 0
        infants_in_lap:
          type: integer
          minimum: 0
        infants_in_seat:
          type: integer
          minimum: 0
        youth:
          type: integer
          minimum: 0
        student:
          type: integer
          minimum: 0
        ages:
          type: array
          items:
            type: integer
            minimum: 0
        residency_country:
          type: string
          minLength: 2
          maxLength: 2
        max_total:
          type: number
          minimum: 0
          exclusiveMinimum: true
          example: 800
        currency:
          type: string
          example: USD
        locale:
          type: string
          example: en-US
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        offset:
          type: integer
          minimum: 0
          default: 0
        sort_by:
          type: string
          enum:
            - lowest
            - recommendation
          default: lowest
        intent:
          $ref: '#/components/schemas/IntentInput'
      required:
        - origins
        - trip_type
      example:
        origins:
          - NYC
        destinations:
          - PAR
        trip_type: roundtrip
        departure_date_ranges:
          - start: '2026-09-01'
            end: '2026-09-30'
        stay_days: 7
        cabin_class: economy
        adults: 1
        currency: USD
    FlightCalendarResponse:
      type: object
      properties:
        itineraries:
          type: array
          items:
            $ref: '#/components/schemas/Itinerary'
        next_page_token:
          type: string
          example: eyJvZmZzZXQiOjIwfQ==
      required:
        - itineraries
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            doc_url:
              type: string
          required:
            - code
            - message
      required:
        - error
    DateRange:
      type: object
      properties:
        start:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
        end:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
      required:
        - start
        - end
      example:
        start: '2026-06-01'
        end: '2026-06-30'
    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
    Itinerary:
      type: object
      properties:
        id:
          type: string
          example: itin_9f3b2a17
        origin:
          type: object
          properties:
            code:
              type: string
            name:
              type: string
          required:
            - code
          example:
            code: JFK
            name: New York John F. Kennedy
        destination:
          type: object
          properties:
            code:
              type: string
            name:
              type: string
          required:
            - code
          example:
            code: CDG
            name: Paris Charles de Gaulle
        total:
          $ref: '#/components/schemas/Amount'
        cabin_class:
          type: string
          example: economy
      required:
        - id
        - origin
        - destination
    Amount:
      type: object
      properties:
        value:
          type: number
          example: 412.5
        currency:
          type: string
          example: USD
        decimal_places:
          type: integer
          example: 2
      required:
        - value
        - currency
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer

````