---
title: "Search stays"
method: GET
path: "/v1/search"
tags: ["Search"]
---

# Search stays

`GET /v1/search`

## Request

- Base URL: `https://threshold.rentals/api`
- URL: `https://threshold.rentals/api/v1/search`
- Auth: one of:
  - none
  - HTTP bearer

Find live listings near a place, optionally for dates and a party. With dates, each result has availability (likely, from cached calendars) and an indicative_total. Always get a quote before stating a price.

## Query parameters

- `place` string
- `near` string
- `radius_km` number
- `country` string
- `check_in` string, date
- `check_out` string, date
- `adults` integer
- `children` integer
- `infants` integer
- `pets` integer
- `min_bedrooms` integer
- `amenities` string[]
- `property_types` string[]
- `step_free_entrance` boolean
- `bedroom_on_entry_level` boolean
- `min_wifi_mbps` number
- `max_total` integer
- `limit` integer
- `cursor` string

## Response `200`

Matching stays, closest and available first

- SearchResults
  - `results` SearchResult[]
    - `id` string
    - `title` string
    - `summary` string
    - `url` string, uri
    - `locality` string
    - `region` string
    - `country` string
    - `distance_km` number
    - `property_type` string
    - `max_guests` integer
    - `bedrooms` integer
    - `bathrooms` number
    - `cover_image` string, uri
    - `booking_mode` 'instant' | 'host_confirms'
    - `verified` boolean
    - `availability` 'likely_available' | 'unavailable': With dates only
    - `indicative_total` Money
      - `amount` integer, required: In cents
      - `currency` string, required
    - `compare_at` CompareAt: Only when the host passes savings on: an estimate of the same stay on the host's main booking site. Present it as an estimate.
      - `site` string
      - `estimated_total` Money
        - `amount` integer, required: In cents
        - `currency` string, required
      - `savings` Money
        - `amount` integer, required: In cents
        - `currency` string, required
      - `basis` string
    - `match_notes` string[]: How the listing meets the filters
    - `host` object: The host's own business name, when they have set a brand. Name the host and say it is verified by Threshold.
      - `name` string
      - `url` string, uri
      - `logo_url` string, uri
      - `verified_by` 'Threshold'
      - `note` string
  - `next_cursor` string, nullable

## Other responses

- `400`: Invalid input (e.g. invalid_dates, unknown_amenity, place_not_found)
- `429`: Rate limited or too many open requests: see Retry-After

---

[API](https://skmtc.dev/threshold/apis/threshold-stays-api.md) · [All operations](https://skmtc.dev/threshold/apis/threshold-stays-api/llms.txt) · [OpenAPI document](https://skmtc.dev/threshold/apis/threshold-stays-api/revisions/7acf3ae91b56?raw)