> ## 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.

# Hotel search

> Searches hotels and vacation rentals for a stay and links each to its
own page.



## OpenAPI

````yaml /public-openapi.json post /v1/hotels/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/hotels/search:
    post:
      tags:
        - Search
      summary: Hotel search
      description: |-
        Searches hotels and vacation rentals for a stay and links each to its
        own page.
      operationId: hotel_search_v1_hotels_search_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HotelSearchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HotelSearchResponse'
        '400':
          description: The stay cannot be searched in this mode or for this organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                type: error
                error:
                  ref_id: search_fcb2b4f3c75e418687bccaa1a8381331
                  message: >-
                    The stay cannot be searched in this mode or 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:
    HotelSearchRequest:
      properties:
        location:
          type: string
          maxLength: 200
          minLength: 2
          title: Location
          description: 'Where to stay: a city, neighborhood, landmark or address.'
          examples:
            - Lisbon
            - Shinjuku, Tokyo
            - near the Eiffel Tower
        check_in_date:
          type: string
          format: date
          title: Check In Date
          description: Check-in date, `YYYY-MM-DD`. Must not have passed.
        check_out_date:
          type: string
          format: date
          title: Check Out Date
          description: >-
            Check-out date, `YYYY-MM-DD`. At most 30 nights after
            `check_in_date`.
        adults:
          type: integer
          maximum: 16
          minimum: 1
          title: Adults
          description: Adult guests.
          default: 2
        children_ages:
          items:
            type: integer
            maximum: 17
            minimum: 0
          type: array
          maxItems: 8
          title: Children Ages
          description: Age of each child guest, 0 to 17.
        rooms:
          type: integer
          maximum: 8
          minimum: 1
          title: Rooms
          description: >-
            Rooms to book. Each room needs an adult. `fast` searches one room
            only.
          default: 1
        property_types:
          items:
            type: string
            enum:
              - hotel
              - vacation_rental
          type: array
          minItems: 1
          title: Property Types
          description: >-
            `hotel` (hotels, hostels, inns) and `vacation_rental` (homes and
            apartments). Defaults to both.
        min_price:
          anyOf:
            - type: number
              minimum: 0
            - type: 'null'
          title: Min Price
          description: Lowest nightly price, before taxes and fees, in `currency`.
        max_price:
          anyOf:
            - type: number
              exclusiveMinimum: 0
            - type: 'null'
          title: Max Price
          description: Highest nightly price, before taxes and fees, in `currency`.
        min_rating:
          anyOf:
            - type: number
              maximum: 5
              minimum: 1
            - type: 'null'
          title: Min Rating
          description: >-
            Lowest guest rating, out of 5. Properties without a rating are left
            out.
        hotel_classes:
          items:
            type: integer
            maximum: 5
            minimum: 1
          type: array
          maxItems: 5
          title: Hotel Classes
          description: >-
            Hotel star classes to keep, 1 to 5. Properties without a class are
            left out.
        free_cancellation:
          type: boolean
          title: Free Cancellation
          description: Only offers that state free cancellation.
          default: false
        sort:
          type: string
          enum:
            - relevance
            - price
            - rating
          title: Sort
          description: >-
            `relevance` (default), `price` (lowest nightly price first) or
            `rating` (highest first).
          default: relevance
        currency:
          type: string
          pattern: ^[A-Za-z]{3}$
          title: Currency
          description: ISO 4217 currency of prices and price filters.
          default: USD
          examples:
            - USD
            - EUR
            - JPY
        mode:
          anyOf:
            - type: string
              enum:
                - advanced
            - type: 'null'
          title: Mode
          description: '`advanced` (default): many sources and offers.'
        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.
          examples:
            - claude-opus-4-7
            - gpt-5.4
            - gemini-3.1-pro
        advanced_settings:
          anyOf:
            - $ref: '#/components/schemas/AdvancedVerticalSearchSettings'
            - type: 'null'
          description: Advanced configuration for result count.
      additionalProperties: false
      type: object
      required:
        - location
        - check_in_date
        - check_out_date
      title: HotelSearchRequest
      description: 'Hotel search request: places to stay in a location for a date range.'
    HotelSearchResponse:
      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. Pass it to later calls made as
            part of the same task.
          examples:
            - session_8a911eb27c7a4afaa20d0d9dc98d07c0
        results:
          items:
            $ref: '#/components/schemas/HotelSearchResult'
          type: array
          title: Results
          description: Places to stay, in the order `sort` asks for.
        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: HotelSearchResponse
      description: Hotel 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.
    AdvancedVerticalSearchSettings:
      properties:
        max_results:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max Results
          description: >-
            Upper bound on results. Defaults to 20; values above the mode's
            maximum are reduced to it, with a warning.
      additionalProperties: false
      type: object
      title: AdvancedVerticalSearchSettings
      description: Advanced vertical search configuration.
    HotelSearchResult:
      properties:
        url:
          type: string
          title: Url
          description: >-
            The property's own website, else a booking site's page for this
            property and these dates. Never a search results page.
        url_kind:
          type: string
          enum:
            - property_website
            - booking_page
          title: Url Kind
          description: '`property_website` or `booking_page`: what `url` links to.'
        name:
          type: string
          title: Name
          description: Property name.
        property_type:
          type: string
          enum:
            - hotel
            - vacation_rental
          title: Property Type
          description: '`hotel` or `vacation_rental`.'
        address:
          anyOf:
            - type: string
            - type: 'null'
          title: Address
          description: Street address.
        latitude:
          anyOf:
            - type: number
            - type: 'null'
          title: Latitude
          description: Property latitude.
        longitude:
          anyOf:
            - type: number
            - type: 'null'
          title: Longitude
          description: Property longitude.
        hotel_class:
          anyOf:
            - type: integer
            - type: 'null'
          title: Hotel Class
          description: Star class, 1 to 5.
        rating:
          anyOf:
            - type: string
              enum:
                - fair
                - good
                - great
                - excellent
            - type: 'null'
          title: Rating
          description: Guest rating tier. Possible values are fair, good, great, excellent.
        images:
          items:
            type: string
          type: array
          title: Images
          description: >-
            Photo URLs, hosted by booking sites. They can stop working; do not
            store them. Empty when there are none.
        price_per_night:
          anyOf:
            - type: number
            - type: 'null'
          title: Price Per Night
          description: Lowest nightly price among `offers`, in `currency`.
        total_price:
          anyOf:
            - type: number
            - type: 'null'
          title: Total Price
          description: Stay total of the offer priced in `price_per_night`.
        currency:
          type: string
          title: Currency
          description: ISO 4217 currency of the prices.
        free_cancellation:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Free Cancellation
          description: >-
            True if any offer states free cancellation, false if every offer
            states none, else omitted.
        offers:
          items:
            $ref: '#/components/schemas/HotelOffer'
          type: array
          title: Offers
          description: Offers that meet the request's filters, cheapest first.
        amenities:
          items:
            type: string
          type: array
          title: Amenities
          description: Listed amenities, e.g. `Free Wi-Fi`, `Pool`.
        check_in_time:
          anyOf:
            - type: string
            - type: 'null'
          title: Check In Time
          description: Earliest check-in time, as listed.
        check_out_time:
          anyOf:
            - type: string
            - type: 'null'
          title: Check Out Time
          description: Latest check-out time, as listed.
      type: object
      required:
        - url
        - url_kind
        - name
        - property_type
        - currency
        - offers
      title: HotelSearchResult
      description: One place to stay.
    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.
    HotelOffer:
      properties:
        seller:
          anyOf:
            - type: string
            - type: 'null'
          title: Seller
          description: Who sells the stay at this price, e.g. the hotel or a booking site.
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          description: >-
            The seller's page for this property and these dates. Omitted when
            only the price is known.
        price_per_night:
          anyOf:
            - type: number
            - type: 'null'
          title: Price Per Night
          description: Nightly price, in `currency`.
        total_price:
          anyOf:
            - type: number
            - type: 'null'
          title: Total Price
          description: Price of the whole stay, in `currency`.
        currency:
          type: string
          title: Currency
          description: ISO 4217 currency.
        free_cancellation:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Free Cancellation
          description: Whether the offer states free cancellation, when known.
      type: object
      required:
        - currency
      title: HotelOffer
      description: One seller's price for the stay.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````