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

# Flight search

> Searches flights and links each itinerary to where it can be booked.



## OpenAPI

````yaml /public-openapi.json post /v1/flights/search
openapi: 3.1.0
info:
  title: Parallel API
  description: Parallel API
  contact:
    name: Parallel Support
    url: https://parallel.ai
    email: support@parallel.ai
  version: 0.1.2
servers:
  - url: https://api.parallel.ai
    description: Parallel API
security:
  - ApiKeyAuth: []
tags:
  - name: Search
    description: >-
      Search returns ranked URLs with extended excerpts suitable for LLM
      consumption. Inputs are a natural-language objective and optional keyword
      queries. Source policies allow including or excluding specific domains and
      have configurable output sizes. The returned extended snippets contain
      dense, relevant information from relevant pages.

      - Result: ranked list with URL, title, and long text excerpts


      Images, Places, Shopping, Hotels and Flights return typed results for one
      kind of content.

      - The Images API returns ranked images from the web. Inputs are keyword
      queries and an optional natural-language objective. `fast`: lowest latency
      and cost. `advanced` (default): slower, with higher-quality results.
      Result: title, direct image URL, source page URL, and dimensions.

      - The Places API finds places such as restaurants, shops and attractions
      near a location. Inputs are a query, and a location name or coordinates.
      `fast`: lowest latency, with fewer results. `advanced` (default): slower,
      with more complete results. Result: name, website, address, phone,
      coordinates, rating tier, price level, and opening hours.

      - The Shopping API finds products for sale at online stores. Inputs are
      keyword queries, an optional natural-language objective, and optional
      price and condition filters. Result: title, store page URL, merchant,
      price, rating, availability, and other stores' offers.

      - The Hotels API finds hotels and vacation rentals with live prices.
      Inputs are a location, check-in and check-out dates, and guests, with
      optional price, rating and star class filters. Result: name, website or
      booking page, address, coordinates, star class, rating tier, nightly and
      total price, and each seller's offer.

      - The Flights API finds itineraries with live fares. Inputs are origin and
      destination airports, travel dates, and passengers, with optional cabin,
      stop, price, airline and time filters. Result: total price, a booking
      link, and each leg's flights, times, stops and layovers.
  - name: Extract
    description: >-
      Extract returns excerpts or full content from one or more URLs. Inputs are
      a list of URLs and an optional search objective and keyword queries. The
      returned excerpts or full content is formatted as markdown and suitable
      for LLM consumption.

      - Result: excerpts or full content from the URL formatted as markdown
  - name: Decisions
    description: >-
      Answer typed choice, score, and probability questions using current web
      evidence, with shared citations for the request.
  - name: Tasks
    description: >-
      The Task API executes web research and extraction tasks. Clients submit a
      natural-language objective with an optional input schema; the service
      plans retrieval, fetches relevant URLs, and returns outputs that conform
      to a provided or inferred JSON schema. Supports deep research style
      queries and can return rich structured JSON outputs. Processors trade-off
      between cost, latency, and quality. Each processor supports calibrated
      confidences.

      - Output metadata: citations, excerpts, reasoning, and confidence per
      field


      Task Groups enable batch execution of many independent Task runs with
      group-level monitoring and failure handling.

      - Submit hundreds or thousands of Tasks as a single group

      - Observe group progress and receive results as they complete

      - Real-time updates via Server-Sent Events (SSE)

      - Add tasks to an existing group while it is running

      - Group-level retry and error aggregation
  - name: FindAll
    description: >-
      The FindAll API discovers and evaluates entities that match complex
      criteria from natural language objectives. Submit a high-level goal and
      the service automatically generates structured match conditions, discovers
      relevant candidates, and evaluates each against the criteria. Returns
      comprehensive results with detailed reasoning, citations, and confidence
      scores for each match decision. Streaming events and webhooks are
      supported.
  - name: Monitor
    description: >-
      The Monitor API watches the web for material changes on a fixed frequency.
      Each monitor runs once on creation and then on its configured schedule,
      emitting events when meaningful changes are detected.

      - `event_stream` monitors track a search query and emit an event for each
      new material change.

      - `snapshot` monitors track a specific task run's output and emit an event
      when the output changes.


      Results can be polled via the events endpoint or delivered via webhooks.
  - name: Memory
    description: >-
      The Memory API retrieves and manages memories created by Tasks, Monitors,
      and FindAll runs. Memories can be personal or isolated with a
      `memory_scope_key`.
  - name: Chat API (Beta)
    description: >-
      The Chat API provides a programmatic chat-style text generation interface.
      It accepts a sequence of messages and returns model responses. Intended
      for assistant-like interactions and evaluation. Streaming responses are
      supported.
  - name: Responses API
    description: >-
      An OpenAI-Responses-compatible interface for answers grounded in live web
      research, with URL citations. Point any Responses-API client — the OpenAI
      Python SDK, OpenAI TypeScript SDK, the Agents SDK, or raw HTTP — at
      `https://api.parallel.ai` with your Parallel API key, set `model` to
      `parallel`, and call `/v1/responses`.

      - `input` accepts a plain string or an array of role/content messages
      (canonical OpenAI shape; text content only).

      - `reasoning.effort` (`low`/`medium`/`high`/`auto`) controls how much
      research is performed, trading response time for answer quality.

      - Multi-turn via `previous_response_id`.

      - Structured outputs via `text.format = {"type": "json_schema", "name":
      ..., "schema": {...}}`.

      - Streaming (`stream=true`) emits the standard OpenAI Responses SSE
      lifecycle: `response.created` and `response.in_progress`, then output item
      / content part / text delta events with URL-citation annotations, the
      matching `*.done` events, and a terminal `response.completed` — or
      `response.failed` if the request fails mid-stream.
paths:
  /v1/flights/search:
    post:
      tags:
        - Search
      summary: Flight search
      description: Searches flights and links each itinerary to where it can be booked.
      operationId: flight_search_v1_flights_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FlightSearchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FlightSearchResponse'
        '400':
          description: Flight search is not supported for this organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                type: error
                error:
                  ref_id: search_fcb2b4f3c75e418687bccaa1a8381331
                  message: Flight search is not supported for this organization.
        '422':
          description: Request validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                type: error
                error:
                  ref_id: search_fcb2b4f3c75e418687bccaa1a8381331
                  message: Request validation error
components:
  schemas:
    FlightSearchRequest:
      properties:
        origins:
          items:
            type: string
            pattern: ^[A-Z]{3}$
            description: IATA airport or metro code, e.g. `SFO` or `NYC`.
          type: array
          maxItems: 7
          minItems: 1
          title: Origins
          description: Departure airports; any of them may be used.
        destinations:
          items:
            type: string
            pattern: ^[A-Z]{3}$
            description: IATA airport or metro code, e.g. `SFO` or `NYC`.
          type: array
          maxItems: 7
          minItems: 1
          title: Destinations
          description: Arrival airports; any of them may be used.
        departure_date:
          type: string
          format: date
          title: Departure Date
          description: Outbound date, YYYY-MM-DD.
        return_date:
          anyOf:
            - type: string
              format: date
            - type: 'null'
          title: Return Date
          description: >-
            Return date, YYYY-MM-DD. Makes the search a round trip, with both
            legs on one airline.
        adults:
          type: integer
          maximum: 9
          minimum: 1
          title: Adults
          default: 1
        children:
          type: integer
          maximum: 8
          minimum: 0
          title: Children
          default: 0
        infants_in_seat:
          type: integer
          maximum: 8
          minimum: 0
          title: Infants In Seat
          default: 0
        infants_on_lap:
          type: integer
          maximum: 8
          minimum: 0
          title: Infants On Lap
          default: 0
        cabin:
          type: string
          enum:
            - economy
            - premium_economy
            - business
            - first
          title: Cabin
          default: economy
        max_stops:
          anyOf:
            - type: integer
              maximum: 2
              minimum: 0
            - type: 'null'
          title: Max Stops
          description: 0 for nonstop only; at most 2.
        max_price:
          anyOf:
            - type: integer
              exclusiveMinimum: 0
            - type: 'null'
          title: Max Price
          description: >-
            Highest total price for all travelers, in `currency`; for a round
            trip, the round-trip total.
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          title: Currency
          description: ISO 4217 currency of `max_price` and of result prices.
          default: USD
          examples:
            - USD
            - EUR
            - JPY
        max_duration_minutes:
          anyOf:
            - type: integer
              exclusiveMinimum: 0
            - type: 'null'
          title: Max Duration Minutes
          description: Longest total travel time per direction.
        include_airlines:
          items:
            type: string
            pattern: ^[A-Z0-9]{2}$
            description: IATA airline code, e.g. `UA`.
          type: array
          maxItems: 10
          title: Include Airlines
          description: Only these airlines.
        exclude_airlines:
          items:
            type: string
            pattern: ^[A-Z0-9]{2}$
            description: IATA airline code, e.g. `UA`.
          type: array
          maxItems: 10
          title: Exclude Airlines
          description: Never these airlines. Not combinable with include_airlines.
        departure_hours:
          anyOf:
            - $ref: '#/components/schemas/HourWindow'
            - type: 'null'
          description: Allowed local departure hours for the outbound flight.
        arrival_hours:
          anyOf:
            - $ref: '#/components/schemas/HourWindow'
            - type: 'null'
          description: >-
            Allowed local arrival hours for the outbound flight, on any date: an
            overnight flight is checked by its arrival hour.
        return_hours:
          anyOf:
            - $ref: '#/components/schemas/HourWindow'
            - type: 'null'
          description: >-
            Allowed local departure hours for the return flight. Needs
            `return_date`.
        return_arrival_hours:
          anyOf:
            - $ref: '#/components/schemas/HourWindow'
            - type: 'null'
          description: >-
            Allowed local arrival hours for the return flight, on any date.
            Needs `return_date`.
        sort:
          type: string
          enum:
            - best
            - price
            - duration
            - departure_time
            - arrival_time
          title: Sort
          description: >-
            `best` (default) balances price, duration and stops. For a round
            trip it also picks the return on the outbound's airline: `price` the
            cheapest, `duration` the shortest, the others the fewest stops
            within 10% of the cheapest. For the cheapest trip on any airlines,
            as separate tickets, search each direction one way.
          default: best
        advanced_settings:
          anyOf:
            - $ref: '#/components/schemas/AdvancedFlightSearchSettings'
            - type: 'null'
          description: Result count.
        mode:
          anyOf:
            - type: string
              enum:
                - advanced
            - type: 'null'
          title: Mode
          description: '`advanced` (default): live fares.'
        session_id:
          anyOf:
            - type: string
              maxLength: 1000
            - type: 'null'
          title: Session Id
          description: >-
            Session identifier that groups related calls made as part of a
            larger task. Echoed back in the response when nonempty; generated by
            the server if omitted, null, or empty.
        client_model:
          anyOf:
            - type: string
            - type: 'null'
          title: Client Model
          description: The model generating this request and consuming the results.
      additionalProperties: false
      type: object
      required:
        - origins
        - destinations
        - departure_date
      title: FlightSearchRequest
      description: 'Flight search request: a one-way or round-trip itinerary search.'
    FlightSearchResponse:
      properties:
        search_id:
          type: string
          title: Search Id
          description: 'Search ID. Example: `search_cad0a6d2dec046bd95ae900527d880e7`'
        session_id:
          type: string
          title: Session Id
          description: >-
            Session identifier, echoed back from the request when nonempty;
            otherwise generated by the server.
        results:
          items:
            $ref: '#/components/schemas/FlightSearchResult'
          type: array
          title: Results
          description: Itineraries, best first by the requested sort.
        warnings:
          anyOf:
            - items:
                $ref: '#/components/schemas/Warning'
              type: array
            - type: 'null'
          title: Warnings
          description: Warnings for the search request, if any.
        usage:
          anyOf:
            - items:
                $ref: '#/components/schemas/UsageItem'
              type: array
            - type: 'null'
          title: Usage
          description: Usage metrics for the search request.
      type: object
      required:
        - search_id
        - session_id
        - results
      title: FlightSearchResponse
      description: Flight search response.
    ErrorResponse:
      properties:
        type:
          type: string
          const: error
          title: Type
          description: Always 'error'.
        error:
          $ref: '#/components/schemas/Error'
          description: Error.
      type: object
      required:
        - type
        - error
      title: ErrorResponse
      description: Response object used for non-200 status codes.
    HourWindow:
      properties:
        earliest:
          type: integer
          maximum: 23
          minimum: 0
          title: Earliest
          description: First allowed hour, 0-23.
        latest:
          type: integer
          maximum: 23
          minimum: 0
          title: Latest
          description: Last allowed hour, 0-23.
      additionalProperties: false
      type: object
      required:
        - earliest
        - latest
      title: HourWindow
      description: Local hours, inclusive.
    AdvancedFlightSearchSettings:
      properties:
        max_results:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max Results
          description: >-
            Upper bound on results, at most 20. Defaults to 20; larger values
            are reduced to 20, with a warning.
      additionalProperties: false
      type: object
      title: AdvancedFlightSearchSettings
      description: Result count.
    FlightSearchResult:
      properties:
        url:
          type: string
          title: Url
          description: >-
            A page on the marketing airline's website where the itinerary can be
            booked: the airline's search results for this trip, or its home page
            when no search link is known.
        price:
          anyOf:
            - type: number
            - type: 'null'
          title: Price
          description: >-
            Total for all travelers, in the request's `currency`: the lowest
            fare listed for this itinerary. For a round trip, the lowest
            round-trip total with this outbound flight. The airline's own fare
            may differ.
        outbound:
          $ref: '#/components/schemas/FlightLegResult'
        inbound:
          anyOf:
            - $ref: '#/components/schemas/FlightLegResult'
            - type: 'null'
          description: The return trip; set for round trips.
      type: object
      required:
        - url
        - outbound
      title: FlightSearchResult
      description: One itinerary and where to book it.
    Warning:
      properties:
        type:
          type: string
          enum:
            - spec_validation_warning
            - input_validation_warning
            - warning
          title: Type
          description: >-
            Type of warning. Note that adding new warning types is considered a
            backward-compatible change.
          examples:
            - spec_validation_warning
            - input_validation_warning
        message:
          type: string
          title: Message
          description: Human-readable message.
        detail:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Detail
          description: Optional detail supporting the warning.
      type: object
      required:
        - type
        - message
      title: Warning
      description: Human-readable message for a task.
    UsageItem:
      properties:
        name:
          type: string
          title: Name
          description: Name of the SKU.
          examples:
            - sku_search
            - sku_extract_excerpts
        count:
          type: integer
          title: Count
          description: Count of the SKU.
          examples:
            - 1
      type: object
      required:
        - name
        - count
      title: UsageItem
      description: Usage item for a single operation.
    Error:
      properties:
        ref_id:
          type: string
          title: Reference ID
          description: Reference ID for the error.
        message:
          type: string
          title: Message
          description: Human-readable message.
        detail:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Detail
          description: Optional detail supporting the error.
      type: object
      required:
        - ref_id
        - message
      title: Error
      description: An error message.
    FlightLegResult:
      properties:
        departure_airport:
          type: string
          title: Departure Airport
        departure_time:
          type: string
          title: Departure Time
        arrival_airport:
          type: string
          title: Arrival Airport
        arrival_time:
          type: string
          title: Arrival Time
        duration_minutes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Duration Minutes
        stops:
          type: integer
          title: Stops
        segments:
          items:
            $ref: '#/components/schemas/FlightSegmentResult'
          type: array
          title: Segments
        layovers:
          items:
            $ref: '#/components/schemas/FlightLayoverResult'
          type: array
          title: Layovers
      type: object
      required:
        - departure_airport
        - departure_time
        - arrival_airport
        - arrival_time
        - stops
        - segments
      title: FlightLegResult
      description: One direction of the trip.
    FlightSegmentResult:
      properties:
        airline:
          type: string
          title: Airline
        flight_number:
          type: string
          title: Flight Number
          description: Marketing flight number, e.g. `BA 301`.
        departure_airport:
          type: string
          title: Departure Airport
        departure_time:
          type: string
          title: Departure Time
          description: Local time, `YYYY-MM-DD HH:MM`.
        arrival_airport:
          type: string
          title: Arrival Airport
        arrival_time:
          type: string
          title: Arrival Time
          description: Local time, `YYYY-MM-DD HH:MM`.
        duration_minutes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Duration Minutes
        aircraft:
          anyOf:
            - type: string
            - type: 'null'
          title: Aircraft
        cabin:
          anyOf:
            - type: string
            - type: 'null'
          title: Cabin
          description: The cabin as listed.
        legroom:
          anyOf:
            - type: string
            - type: 'null'
          title: Legroom
        overnight:
          type: boolean
          title: Overnight
          default: false
      type: object
      required:
        - airline
        - flight_number
        - departure_airport
        - departure_time
        - arrival_airport
        - arrival_time
      title: FlightSegmentResult
      description: One flown segment.
    FlightLayoverResult:
      properties:
        airport:
          type: string
          title: Airport
        duration_minutes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Duration Minutes
        overnight:
          type: boolean
          title: Overnight
          default: false
      type: object
      required:
        - airport
      title: FlightLayoverResult
      description: Time on the ground between two segments.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````