Structured property filter — bypasses natural-language extraction.
Use this when filters are already known (from prior turns or external
state) and you want to skip the OpenAI NLU step. For free-text user
queries like "cheap apartments near the beach", use `search_properties`
instead. Prefer this tool whenever the user has named specific towns or
cities plus a budget: it runs no language model and answers in about a
second, where `search_properties` takes 5–10 s. Pass towns/cities rather
than a landscape region or a whole country. A `{"is_error": true, ...}`
reply carries a `next_action` — follow it instead of retrying unchanged.
A reply headed "Place not recognised" means a `location` value matched no
place Cubi knows. Ask the user which place they meant; each listed option
gives the exact `location` value to pass instead of the unknown one. Do
not widen other filters to rescue that zero.
All list args are AND-combined; within a list, items are typically OR.
Locations accept countries, regions, cities, neighborhoods. Types accept
apartment/house/villa/townhouse/penthouse/studio/land/etc.
Features are structural (Balcony, Pool, Sea View); amenities are services
(Gym, Concierge, Security).
`transaction_type` picks sale vs rent. Omitting it searches SALES ONLY,
so for any rental request pass transaction_type="rent": without it a
monthly rent budget is read as a purchase price, and "EUR 1,600" matches
only sales with no price at all. For rentals `price_period` says what the
price is per (a EUR 1,600 "month" rental and a EUR 1,600,000 sale are both
"1600" to a bare min/max_price bound). `radius_center` + `radius_km`
search around a named place instead of within it.
Prices are in each market's own currency: PLN in Poland, CZK in Czechia,
EUR in the euro countries. When the user states a budget in a different
currency ("up to 1,000 euros a month" in Warsaw), pass the amount as they
said it plus `price_currency` (ISO code, e.g. "EUR"): Cubi converts it at
the day's ECB reference rate and the reply says what it applied. Do not
convert it yourself, and never send a euro amount bare for a PLN market —
it is read as 1,000 PLN, a quarter of the budget.
Note prices may be missing: a listing marked "Price on request" has no
price at all, so it is NOT excluded by min_price/max_price and will still
appear under a budget cap (in the default newest-first order it is
listed after the priced matches).
Every reply ends with a `Cubi request id` (req_…). When you then fetch one
of the listings with get_listing, or narrow this search with another
filter_listings call, pass it as `parent_request_id` — optional, and it
changes nothing in the answer; it lets Cubi tie the follow-up to this
search.
`updated_since` is for WATCHING a search rather than running it. Pass the
timestamp of your last check (ISO-8601, e.g. "2026-09-21T06:00:00Z") and
you get back only the listings whose data has changed since then, usually
none. A listing's timestamp moves when its data changes, not when a sync
re-confirms it unchanged, so an empty result means "nothing moved" — which
is the useful answer for a monitor. Use it instead of re-fetching every
result on a timer: it is one call rather than one per listing. A watched
call answers with `changed` (true/false), `checked_at` — pass it back as
`updated_since` on the next call — and `next_poll_at` /
`next_poll_after_seconds`: listing data only moves at the ingestion sync
(05:30 and 21:00 UTC), so a repeat before that instant cannot return
anything new. When nothing changed the reply is a small JSON object rather
than cards. Watched calls are never served from cache.
`dimension_filters` carries measurable constraints the named fields do
not have: a list of {"dimension_key", "op", "value", "value_max"?,
"weight"?}. Keys: quantity.parking_spaces, quantity.balconies,
quantity.rooms_total, area.balcony_total, area.terrace_total,
area.garden, level.total_floors, dimension.ceiling_height (and the hot
ones — quantity.bedrooms, quantity.bathrooms, area.living, area.plot,
level.floor_number — which are the same as the min_/max_ fields). op is
eq|gt|gte|lt|lte|between; values are m², metres, counts or floor
numbers. weight "must" (default) filters, "nice" only ranks. Example:
[{"dimension_key": "area.terrace_total", "op": "gte", "value": 20}].
`city_only=true` counts a name that is also a district, province or
region ("Porto", "Valencia") as the city only — without it, a Porto search
also lists towns across Porto district. The reply's `city_only` names the
places it pinned.
`sort` defaults to "newest": the most recently listed matches come first,
so the top `limit` rows are the freshest part of the market and a repeat
call surfaces new listings as they arrive. "relevance" returns the
engine's stable order instead, which is not recency.
Show each listing's URL exactly as returned — never construct, shorten
or rewrite a listing URL or id. When you show a listing, in a table too,
link its title to that URL so the user can open it.
`page_token` pages the same search: a reply that ends with "More
matches" gives the exact `page_token` for the next page. When the user
wants to see more, call again with the SAME arguments plus that token —
never re-run a narrower or different search to "show more". Offer the
next page whenever the reply says more exist.
Returns:
Markdown summary + numbered listing cards (count and avg price up top).
View input schema
{
"type": "object",
"properties": {
"location": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Location",
"description": "Places to search, OR-combined: countries, regions, cities or neighbourhoods. Prefer towns/cities over a landscape region or a whole country."
},
"type": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Type",
"description": "Property types, OR-combined: apartment, house, villa, townhouse, penthouse, studio, land, etc."
},
"transaction_type": {
"anyOf": [
{
"enum": [
"sale",
"rent"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Transaction Type",
"description": "\"sale\" or \"rent\". Omitted means SALES ONLY — pass \"rent\" for any rental request."
},
"price_period": {
"anyOf": [
{
"enum": [
"night",
"week",
"month"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Price Period",
"description": "For rentals, what the price is per: night, week or month."
},
"min_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Min Price",
"description": "Lowest asking price, in the market's currency unless price_currency is given."
},
"max_price": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Price",
"description": "Highest asking price, in the market's currency unless price_currency is given. Listings with no price (\"Price on request\") are not excluded."
},
"price_currency": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Price Currency",
"description": "ISO currency code of min_price/max_price when it differs from the market's (e.g. \"EUR\" for a Warsaw budget). Cubi converts at the day's ECB rate; do not convert yourself."
},
"min_bedrooms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Min Bedrooms",
"description": "Minimum number of bedrooms."
},
"max_bedrooms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Bedrooms",
"description": "Maximum number of bedrooms (equal to min_bedrooms for \"exactly N\")."
},
"min_floor": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Min Floor",
"description": "Lowest floor number of the unit."
},
"max_floor": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Floor",
"description": "Highest floor number of the unit."
},
"min_living_area": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Min Living Area",
"description": "Minimum living area in m². Rarely stated in the UK and on many Maltese rentals; a listing without it is excluded (see field_coverage)."
},
"max_living_area": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Living Area",
"description": "Maximum living area in m²."
},
"min_plot_area": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Min Plot Area",
"description": "Minimum plot (land) area in m². Rarely stated in Italy and on many rentals; a listing without it is excluded (see field_coverage)."
},
"max_plot_area": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Plot Area",
"description": "Maximum plot (land) area in m²."
},
"min_bathrooms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Min Bathrooms",
"description": "Minimum number of bathrooms. Often not stated in Germany and Poland; a listing without it is excluded (see field_coverage)."
},
"max_bathrooms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Bathrooms",
"description": "Maximum number of bathrooms."
},
"has_parking": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"title": "Has Parking",
"description": "true to require parking."
},
"min_year_built": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Min Year Built",
"description": "Earliest construction year. Rarely listed outside the Netherlands, German sales and a few small markets (rentals almost never), and a listing without one is excluded: expect few or no matches, and if field_coverage comes back, offer to drop the filter rather than change the year."
},
"max_year_built": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"title": "Max Year Built",
"description": "Latest construction year. Same sparse coverage as min_year_built."
},
"features": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Features",
"description": "Structural features to match, e.g. Balcony, Pool, Sea View."
},
"amenities": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Amenities",
"description": "Building services to match, e.g. Gym, Concierge, Security."
},
"radius_center": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Radius Center",
"description": "A named place to search around, instead of within (use with radius_km)."
},
"radius_km": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"title": "Radius Km",
"description": "Search radius in km around radius_center."
},
"dimension_filters": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"default": null,
"title": "Dimension Filters",
"description": "Measurable constraints without a named field: a list of {\"dimension_key\", \"op\", \"value\", \"value_max\"?, \"weight\"?}; op eq|gt|gte|lt|lte|between, weight must (filters, default) or nice (ranks). Keys are listed in the tool description."
},
"updated_since": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Updated Since",
"description": "ISO-8601 timestamp of your last check: return only listings whose data changed since then (for watching a search). Pass back the reply's checked_at next time."
},
"sort": {
"anyOf": [
{
"enum": [
"newest",
"relevance"
],
"type": "string"
},
{
"type": "null"
}
],
"default": "newest",
"title": "Sort",
"description": "\"newest\" (default, most recently listed first) or \"relevance\" (the engine's stable order)."
},
"city_only": {
"default": false,
"title": "City Only",
"type": "boolean",
"description": "true to read a name that is also a district or region (\"Porto\") as the city only."
},
"parent_request_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Parent Request Id",
"description": "Optional `Cubi request id` (req_…) of the search this call narrows; changes nothing in the answer."
},
"lang": {
"default": "en",
"title": "Lang",
"type": "string",
"description": "ISO 639-1 code of the user's language (en/pt/es/fr/de/nl/ru). Defaults to en."
},
"limit": {
"default": 10,
"title": "Limit",
"type": "integer",
"description": "How many listings to return (1-50, default 10)."
},
"page_token": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Page Token",
"description": "The page_token from a reply's \"More matches\" line, to get the next page of the SAME search."
}
},
"title": "filter_listingsArguments"
}