Search vacation rentals
search_vacation_rentalsSearch about 90,000 vacation rentals and longer-stay homes from independent hosts and property managers in 70+ countries and territories. Each result lists the ways it can be booked that CielStay holds: the host's own booking site or engine (directUrl / referenceUrl), bookUrl (the same booking page opened through CielStay, which lets CielStay count the referral) and a CielStay listing page (cielstayUrl). CielStay does not take bookings or payments. Results are ranked by fit to the request, with a photo, a price (the average per night of a 3-night stay including the host's fees, before taxes; or per month for monthly homes) and a match score. Suited to finding a place to stay, or to checking whether a home seen on another site can be booked with its host. Follow-ups to a search ("with ping pong", "cheaper", "bigger") are handled by refine_search, or here with previousIntent; without either, a follow-up that names no place is searched everywhere. Each result carries bookUrl (the host's booking page) and, where someone can receive a message about the home, messageHostUrl (its message form); for those, contact_host sends the traveller's first message, free, for questions or monthly stays.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Number of results to return (1–20). Default 5. | |
| query | Yes | Natural language search query: location, dates, group, and what the stay is for. Examples: "cozy cabin near Zion National Park for a couple", "pet-friendly beachfront with a hot tub in Hawaii", "modern loft in Austin walkable to nightlife for 4 adults". Put WHO the guest is in the separate `persona` argument rather than here. | |
| guests | No | Number of guests. Defaults to 2 if omitted. | |
| intent | No | OPTIONAL FAST PATH. If you have already parsed the traveller's request, send it here and CielStay skips its own parse — measured 2.3s to 0.06s with identical results. Shape: {"vibePrefs":["quiet","rustic"],"aestheticPrefs":["historic","cabin"],"activities":["hiking"],"filters":{"guests":4,"checkIn":"2026-11-13","checkOut":"2026-11-16"}}. Trusted, not re-validated. You can also pass back the `currentIntent` from a previous response. | |
| source | No | Limit results to homes from one booking source we hold: a booking-engine or host-site name ("guesty", "hospitable", "escapia", a host brand such as "haven") or its domain; a comma list for several. The list with live counts is at https://www.cielstay.com/api/v1/sources. Booking platforms such as Airbnb or Vrbo are not sources here, because CielStay lists hosts' own sites. The same filter can be written in the query itself as source:<name> or site:<domain>. | |
| checkin | No | Check-in date in YYYY-MM-DD format. Omit if flexible or unknown. | |
| persona | No | Who the guest is, in a few sentences of plain prose — what they like, what the trip is for, and what they want to avoid. CielStay embeds this and ranks on it, so it changes which homes come back rather than filtering them. Example: "Travelling with a dog and two teenagers. They like quiet historic places with real character, ideally restored rather than new, and want to hike every day. They avoid resorts, condo complexes and anywhere with nightlife." Any length is used; a few sentences rank more precisely than keywords. `traveller` carries the same context as short fields. Never stored. | |
| checkout | No | Check-out date in YYYY-MM-DD format. Omit if flexible or unknown. | |
| traveller | No | What the traveller has said about who is going and what they want, in short fields (any subset). Preferences only, not names, contact details or health information. Used for ranking and never stored; echoed back in rankedFor.traveller. | |
| minBedrooms | No | Minimum number of bedrooms required. | |
| previousIntent | No | The `currentIntent` from the previous CielStay search in this conversation, when this request follows on from it ("with a pool", "cheaper", "that area but bigger"). Keeps its place, party and dates; a request that names a new place still starts a new search. | |
| maxPricePerNight | No | Maximum nightly price in USD. | |
| mustHaveAmenities | No | Amenities the listing must have, in plain English. Filterable: hot tub, pool, kitchen, washer/dryer, air conditioning, parking, workspace, waterfront, EV charger, pet friendly. Anything else is reported in _amenityWarning as not filterable rather than silently dropped. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| notice | No | ||
| hasMore | No | ||
| results | Yes | ||
| rankedFor | No | What these results were ranked for: place, guests, dates, amenities, traveller | |
| totalFound | No | ||
| currentIntent | No | Pass to refine_search as previousIntent to keep place and dates | |
| rankingQuestion | No | Present when nothing is known about the traveller: the question whose answer would most change this ranking. An answer can be sent as `traveller` |