# Refine a search > **Casafari is the AI agent-native real estate data intelligence platform.** The most complete property index in Europe: a deduplicated, cleaned property graph of residential and commercial property, for sale and for rent, in 16 countries. Every property is one record with its full price and market history. [How the property graph is built](/docs/property-graph). `POST https://platform.casafari.com/v1/claro/search/refine` [Claro AI](/docs/claro) · [REST API](/docs/claro#rest-api). Send `Authorization: Bearer $CASAFARI_API_KEY`: a platform API key or OAuth access token, metered in platform units; see [platform sign-in](/docs/rest#platform-api-keys) and [Claro AI](/docs/claro#keys). On the platform this is `POST https://platform.casafari.com/v1/claro/search/refine`; `POST /v1/search/refine` is Claro's own path, which the platform adds `/claro` to. The platform forwards the call to Claro unchanged: Claro's `Claro-Version` header and its error bodies (`{"error":{"code","message"}}`, with `rate_limited` and `quota_reached` on a 429) pass through. Over MCP: [`refine_search`](/docs/claro/refine_search) (equivalent). See [MCP and REST compared](/docs/parity#claro-ai). ## Description Change part of an earlier search in plain words ("bigger, at least 200 m²", "Barcelona too", "drop the corner") and run it again, as a new search with its own search_id and pages. Uses the search_id from search_premises; searches are kept 24 hours. Results as search_premises gives them, location figures with `location_sources`. Up to 200 results a page (50 with a publishable key). `next_cursor` gets the next page: send it as `cursor` (alone, with `limit` if you like); the order is fixed when the search runs and stays the same for its 24 hours, so pages never repeat or skip a premises. `page` gives offset, limit and the total ranked. The read-through (`check`) runs only for pages of up to 50. ## Request body Content type `application/json`. Required. Type: `object`. - `search_id` (string, required) - `change` (string, optional): What to change, in plain words. Required unless cursor is sent. - `limit` (integer, optional): Results a page, up to 200; above 50 check is off. 1–200; default 10. - `cursor` (string, optional): next_cursor from an earlier answer: returns that search's next page, same criteria and order. Send without brief, criteria or change. - `check` (boolean, optional) default true. - `insights` (boolean, optional): Add `insights`, charts as data over every match, each with a one-sentence answer, its count, scope, source and date: per criterion how many matches meet it, leave it unsaid or contradict it (and how many would state everything without it); with one price limit, what it reaches among premises of this kind and place before the limit, else what the matches ask per m²; and where the matches are by district or town. Asking prices; each unit counted once. default false. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://platform.casafari.com/v1/claro/search/refine" \ -H "Authorization: Bearer $CASAFARI_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "search_id": "" }' ``` ## Responses ### 200 Refine a search No body. Example from the API description (long arrays shortened): ```json { "search_id": "s_7hQ2", "criteria": { "operation": "rent", "cities": [ "madrid" ], "area_min": 120, "smoke_extraction": true }, "counts": { "matching": 14, "all_criteria_stated": 6, "some_not_stated": 8 }, "not_applied": [], "results": [ { "id": "pm_3kX9vQ2LmT8a", "title": "Local comercial en esquina", "type": "retail", "city": "madrid", "city_name": "Madrid", "district": "Centro", "address": null, "location_precision": "approximate", "coordinates": { "lat": 40.42, "lon": -3.705, "precision": "approximate" }, "for_rent": true, "for_sale": false, "rent_eur_month": 5000, "sale_eur": null, "area_m2": 200, "floor_number": 0, "street_level": true, "floors": 1, "frontage_m": null, "smoke_outlet": true, "business_transfer": false, "criteria": [ { "criterion": "smoke_extraction", "status": "met", "evidence": "con salida de humos" } ], "photos": [ "https://st2.retelligence.co/c/1234/c/de/abcde350.jpg" ], "excerpt": "Local en esquina con salida de humos. Zona de mucho paso.", "agency": { "name": "Agencia Sol", "listing_url": "https://agenciasol.es/1" }, "location": { "footfall_daily_walk_5min": 50000, "footfall_weekday_avg_walk_5min": 52000, "footfall_weekend_avg_walk_5min": 41000, "residents_walk_10min": 20000, "residents_drive_10min": 300000, "residents_age_30_44_walk_10min": 5200, "households_walk_10min": 9000, "households_income_above_57824_walk_10min": null, "spending_power_total_eur_walk_10min": 310000000, "spending_power_per_resident_eur_walk_10min": 15500, "cafes_walk_5min": 12, "transit_stops_walk_5min": 5 }, "location_sources": { "computed_at": "2026-10-12", "groups": [ { "fields": [ "footfall_daily_walk_5min", "footfall_weekday_avg_walk_5min" ], "unit": "footfall index: summed per-cell daily count within the walk, not distinct people (weekday/weekend are daily averages; the others split the daily count)", "source": "Targomo Footfall estimates (collection 234)", "vintage": "2024" }, { "fields": [ "residents_walk_10min", "residents_drive_10min" ], "unit": "residents", "source": "Targomo, MB Research sociodemographics (collection 87)", "vintage": "2024" } ] } } ], "page": { "offset": 0, "limit": 200, "total": 14 }, "next_cursor": null, "notes": [ "The read-through of the results' text (check) runs only for pages of up to 50; results are ranked by criteria and meaning only." ] } ``` ### 400 Invalid request Type: `object`. - `error` (object, optional) - `code` (string, required) - `message` (string, required) ### 401 Missing or invalid key Type: `object`. - `error` (object, optional) - `code` (string, required) - `message` (string, required) ### 403 No access Type: `object`. - `error` (object, optional) - `code` (string, required) - `message` (string, required) ### 429 Rate limited Type: `object`. - `error` (object, optional) - `code` (string, required) - `message` (string, required) ## Related pages - [Search commercial premises (POST /v1/search)](/docs/rest/claro/search-premises) - [Get one premises (GET /v1/premises/{id})](/docs/rest/claro/get-premises) - [Compare premises (POST /v1/compare)](/docs/rest/claro/compare-premises) - [Location figures (POST /v1/location)](/docs/rest/claro/explain-location) - [Claro AI: all its MCP tools and REST operations](/docs/claro) - [Connect Claro to an MCP client](/docs/claro/connect) - [MCP vs REST API compared](/docs/parity)