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

# Search flights

> Find itineraries for a route and travel dates.

Find itineraries for a route and travel dates. Omit `return_date` for a one-way trip.

* **One way:** use a returned itinerary `id` to request [booking options](https://docs.sanfoundation.com/api-reference/flights-bookings.md).
* **Round trip:** use an outbound `id` to select [return options](https://docs.sanfoundation.com/api-reference/flights-returns.md), then request booking options using the selected return's ID.

IDs and prices can be absent. Keep each ID with the route, dates, country, and currency that produced it. Times are local to each airport; durations are in minutes. Flight search is unpaginated.

## Example round trip

Generate future dates with Python 3:

```bash theme={null}
DEPARTURE_DATE=$(python3 -c 'from datetime import datetime, timedelta, timezone; print((datetime.now(timezone.utc) + timedelta(days=30)).date())')
RETURN_DATE=$(python3 -c 'from datetime import datetime, timedelta, timezone; print((datetime.now(timezone.utc) + timedelta(days=37)).date())')

curl --get 'https://api.sanfoundation.com/v1/flights/search' \
  --header "Authorization: Bearer $SAN_API_KEY" \
  --data-urlencode 'from=SIN' \
  --data-urlencode 'to=NRT' \
  --data-urlencode "departure_date=$DEPARTURE_DATE" \
  --data-urlencode "return_date=$RETURN_DATE" \
  --data-urlencode 'currency=USD'
```


## OpenAPI

````yaml https://api.sanfoundation.com/openapi.json GET /v1/flights/search
openapi: 3.0.0
info:
  title: SAN API
  description: >-
    Web data and context for agents, served by a network of miners running real
    browsers on residential connections. One resource per thing an agent asks
    for: search the web, read the news, find places, hotels and flights, and
    quote a symbol. Present an API key as `Authorization: Bearer san_...`. Every
    response is snake_case JSON and every error is `{ error: { code, message,
    param } }`.
  version: 0.0.1
  contact: {}
servers: []
security: []
tags:
  - name: web
    description: Web search
  - name: news
    description: News search
  - name: places
    description: Places search
  - name: hotels
    description: Stays search
  - name: flights
    description: Flight search
  - name: finance
    description: Quotes and charts
  - name: shopping
    description: Products and sellers
  - name: account
    description: Plan and remaining budget
paths:
  /v1/flights/search:
    get:
      tags:
        - flights
      summary: Search flights
      description: >-
        Itineraries for a route and date. Supplying `return_date` makes it a
        round trip; leaving it out makes it one way. A round trip lists outbound
        options, each with an `id` you pass to the returns endpoint to see what
        pairs with it.
      operationId: FlightsController_search
      parameters:
        - name: country
          required: false
          in: query
          description: ISO 3166-1 alpha-2. Defaults to `us`.
          schema:
            type: string
            example: us
        - name: currency
          required: false
          in: query
          description: ISO 4217. Defaults to the currency of `country`.
          schema:
            type: string
            example: USD
        - name: return_date
          required: false
          in: query
          description: YYYY-MM-DD, after `departure_date`. Omit for one way.
          schema:
            example: '2026-10-19'
            type: string
        - name: departure_date
          required: true
          in: query
          description: YYYY-MM-DD. Not in the past.
          schema:
            type: string
            example: '2026-10-15'
        - name: to
          required: true
          in: query
          schema:
            example: NRT
            type: string
        - name: from
          required: true
          in: query
          description: Airport code or city name.
          schema:
            type: string
            example: SIN
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightsSearchResponseDto'
        '400':
          description: A parameter is missing, invalid or not recognized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorDto'
        '401':
          description: Invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorDto'
        '429':
          description: Monthly quota exhausted. Hard stop, no overage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorDto'
        '503':
          description: No miner and no fallback could serve the request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicErrorDto'
      security:
        - api_key: []
        - x-api-key: []
components:
  schemas:
    FlightsSearchResponseDto:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Id of this request. Quote it when reporting a problem.
        took_ms:
          type: number
          example: 1420
          description: How long the request took, in milliseconds.
        request:
          type: object
          additionalProperties: true
          description: >-
            The parameters as accepted, after defaults and normalization. What
            the request actually ran with.
          example:
            query: coffee
            country: us
            page: 1
        results:
          type: array
          items:
            $ref: '#/components/schemas/ItineraryDto'
        next_page:
          type: number
          nullable: true
          example: null
          description: 'Always null: one search returns the whole set.'
        price_insights:
          $ref: '#/components/schemas/PriceInsightsDto'
        selected_outbound:
          description: The outbound these return options were listed for.
          allOf:
            - $ref: '#/components/schemas/SelectedOutboundDto'
      required:
        - id
        - took_ms
        - request
        - results
        - next_page
    PublicErrorDto:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/PublicErrorBodyDto'
      required:
        - error
    ItineraryDto:
      type: object
      properties:
        position:
          type: number
          example: 1
        id:
          type: string
          example: san1.QkFEQ0FGRTAxMjM0NTY3ODk
          description: >-
            Opaque handle for this itinerary. On a round trip outbound it opens
            the returns endpoint; on a one way or a return option it opens the
            bookings endpoint.
        recommended:
          type: boolean
          example: true
          description: Present on the itineraries ranked best for this route.
        price:
          type: number
          example: 698
        currency:
          type: string
          example: USD
        total_duration:
          type: number
          example: 495
          description: Door to door minutes.
        segments:
          type: array
          items:
            $ref: '#/components/schemas/FlightSegmentDto'
        layovers:
          type: array
          items:
            $ref: '#/components/schemas/FlightLayoverDto'
        carbon_grams:
          type: number
          example: 421000
          description: Estimated emissions for this itinerary, in grams.
        next_day:
          type: boolean
          example: true
          description: Present when the itinerary lands on a later calendar day.
        type:
          type: string
          example: Round trip
      required:
        - position
        - segments
    PriceInsightsDto:
      type: object
      properties:
        lowest_price:
          type: number
          example: 457
        price_level:
          type: string
          example: typical
    SelectedOutboundDto:
      type: object
      properties:
        segments:
          type: array
          items:
            $ref: '#/components/schemas/FlightSegmentDto'
      required:
        - segments
    PublicErrorBodyDto:
      type: object
      properties:
        code:
          type: string
          enum:
            - unauthorized
            - missing_parameter
            - invalid_parameter
            - not_found
            - quota_exceeded
            - rate_limited
            - unavailable
            - expired
            - internal_error
          example: missing_parameter
        message:
          type: string
          example: Missing parameter `query`.
        param:
          type: string
          example: query
          description: The parameter at fault, when one parameter is at fault.
      required:
        - code
        - message
    FlightSegmentDto:
      type: object
      properties:
        from:
          $ref: '#/components/schemas/FlightAirportDto'
        to:
          $ref: '#/components/schemas/FlightAirportDto'
        departure:
          type: string
          example: 2026-10-15 09:20
          description: Same value as `from.time`.
        arrival:
          type: string
          example: 2026-10-15 17:35
          description: Same value as `to.time`.
        airline:
          type: string
          example: Singapore Airlines
        flight_number:
          type: string
          example: SQ 634
          description: Rarely available on a search result.
        duration:
          type: number
          example: 435
          description: Minutes in the air.
        aircraft:
          type: string
          example: Boeing 787
      required:
        - from
        - to
    FlightLayoverDto:
      type: object
      properties:
        id:
          type: string
          example: HKG
        name:
          type: string
          example: Hong Kong International Airport
        duration:
          type: number
          example: 180
          description: Minutes on the ground.
        overnight:
          type: boolean
          example: false
    FlightAirportDto:
      type: object
      properties:
        id:
          type: string
          example: SIN
        name:
          type: string
          example: Singapore Changi Airport
        time:
          type: string
          example: 2026-10-15 09:20
          description: Local time at this airport, 24 hour.
  securitySchemes:
    api_key:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: 'Public API key: `Authorization: Bearer san_...`.'
    x-api-key:
      type: apiKey
      in: header
      name: X-Api-Key
      description: The same public API key, as a header.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.