Refine a search
https://platform.casafari.com/v1/claro/search/refineSend Authorization: Bearer $CASAFARI_API_KEY: a platform API key or OAuth access token, metered in platform units; see platform sign-in and Claro AI. 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 (equivalent). MCP and REST compared.
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_idstringrequiredchangestringlimitintegercursorstringcheckbooleaninsightsbooleaninsights, 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.Example request
Placeholders only: replace the token and the values with your own.
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": "<search_id>"
}'Responses
200 Refine a search
No body.
Example from the API description (long arrays shortened)
{
"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.
Show the response shape (3 fields)
errorobject2 properties
codestringrequiredmessagestringrequired401 Missing or invalid key
Type: object.
Show the response shape (3 fields)
errorobject2 properties
codestringrequiredmessagestringrequired403 No access
Type: object.
Show the response shape (3 fields)
errorobject2 properties
codestringrequiredmessagestringrequired429 Rate limited
Type: object.
Show the response shape (3 fields)
errorobject2 properties
codestringrequiredmessagestringrequired