# Search alerts (v1) > **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://api.casafari.com/api/v1/listing-alerts/search` [Alerts](/docs/alerts) · [REST API](/docs/rest/alerts). Send `Authorization: Bearer $CASAFARI_TOKEN`; see [how to get a token](/docs/rest#get-a-token). Over MCP: no tool does this. See [MCP and REST compared](/docs/parity#alerts). ## Description Returns paginated list of alerts (by requested parameters) for currently authenticated user. ## Query parameters - `limit` (integer, optional): Number of results to return per page. ≤ 100; default 20. - `offset` (integer, optional): The initial index from which to return the results. ≤ 50000. - `order_by` (string, optional): The field by which to sort the results. Values: `alert_date`, `-alert_date`, `alert_id`, `-alert_id`, `created_at`, `-created_at`, `updated_at`, `-updated_at`. default "-alert_date". - `alert_subtype` (string, optional): Get only alerts of the specific subtype. Invalid values are ignored. **This field is deprecated and will be removed in the next major update.** **Please, use `alert_subtypes` field in the body parameters instead.** Values: `new`, `price_up`, `price_down`, `reserved`, `delisted`, `sold`. ## Request body Content type `application/json`. Optional. Type: `object`. - `operation` (string, required): Operation type. Values: `sale`, `rent`. - `location_ids` (integer[], optional): List of location IDs, as returned by the POST /api/v1/references/locations endpoint. at most 100 items; 1–2147483647. - `custom_location` (object[], optional): Closed polygon of geo-points to search within. First and last points must match. **This field is deprecated and will be removed in the next major update.** **Please, use `custom_locations` field instead.** at least 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `custom_locations` (object[][], optional): List of closed polygons of geo-points to search within. Each polygon must contain at least 4 points. First and last points must match in each polygon. Maximum 4 polygons allowed. at most 4 items. - `latitude` (number, required): Latitude. -90–90. - `longitude` (number, required): Longitude. -180–180. - `types` (string[], optional): Country availability per type is available at the GET /api/v1/references/types endpoint. Property types by type groups: **apartment:** penthouse, dachgeschosswohnung, erdgeschosswohnung, apartment, etagenwohnung, studio, duplex **house:** townhouse, reihenmittelhaus, landwirtschaftliche_betriebe, country_house, family_house (DEPRECATED), villa, palace, chalet, zweifamilienhaus, country_estate, reihenendhaus, reihenhaus, bungalow, einfamilienhaus, house **room:** room **building:** office_building, apartment_building, mix_use_building **investment:** retail, hotel, warehouse, office, restaurant, industrial, other_commercial, werkstatt **plot:** rural_plot, urban_plot, plot (DEPRECATED) **other:** garage, other, parking Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `conditions` (string[], optional): Property conditions, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `alert_date_from` (string (date), optional): Start date (in the format `YYYY-MM-DD`) of the period for alerts of interest. - `alert_date_to` (string (date), optional): End date (in the format `YYYY-MM-DD`) of the period for alerts of interest. - `created_at_from` (string (date-time), optional): Start date and time (in the format `YYYY-MM-DDTHH:mm:ss`) to filter alerts by their creation in the database (UTC). Useful for incremental sync to avoid fetching already fetched data. - `created_at_to` (string (date-time), optional): End date and time (in the format `YYYY-MM-DDTHH:mm:ss`) to filter alerts by their creation in the database (UTC). Useful for incremental sync to avoid fetching already fetched data. - `created_at_with_photos_from` (string (date-time), optional): Start date and time (in the format YYYY-MM-DDTHH:mm:ss) to filter alerts by their creation in the database (UTC), only including alerts for which photo processing has been completed. Use it to fetch alerts with already assigned photos. Note: Some alerts may still not have photos if the original listing did not include any. - `created_at_with_photos_to` (string (date-time), optional): End date and time (in the format YYYY-MM-DDTHH:mm:ss) to filter alerts by their creation in the database (UTC), only including alerts for which photo processing has been completed. Use it to fetch alerts with already assigned photos. Note: Some alerts may still not have photos if the original listing did not include any. - `statuses` (string[], optional): Current status of the listing. Values: `active`, `reserved`, `hold`, `sold`, `rented`. - `price_from` (integer, optional): Minimum price value. 1–2147483647. - `price_to` (integer, optional): Maximum price value. 1–2147483647. - `price_per_sqm_from` (integer, optional): Minimum value for price per square meter. 1–2147483647. - `price_per_sqm_to` (integer, optional): Maximum value for price per square meter. 1–2147483647. - `bedrooms_from` (integer, optional): Minimum number of bedrooms. 0–15000. - `bedrooms_to` (integer, optional): Maximum number of bedrooms. 0–15000. - `bathrooms_from` (integer, optional): Minimum number of bathrooms. 1–15000. - `bathrooms_to` (integer, optional): Maximum number of bathrooms. 1–15000. - `total_area_from` (integer, optional): Minimum total area. 1–10000000. - `total_area_to` (integer, optional): Maximum total area. 1–10000000. - `plot_area_from` (integer, optional): Minimum plot area. 1–10000000. - `plot_area_to` (integer, optional): Maximum plot area. 1–10000000. - `construction_year_from` (integer, optional): Minimum construction year. 1–3000. - `construction_year_to` (integer, optional): Maximum construction year. 1–3000. - `floor` (string, optional): Floor type. **This field is deprecated and will be removed in the next major update.** **Please, use `floors` field instead.** Values: `no_floor`, `ground`, `middle`, `top`. - `floors` (string[], optional): List of floor types. Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, optional): Property view orientation. Values: `exterior`, `interior`. - `view` (string, optional): View from the property. " **This field is deprecated and will be removed in the next major update.** **Please, use `views` field instead.**" Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], optional): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, optional): Cardinal direction the property faces. " **This field is deprecated and will be removed in the next major update.** **Please, use `directions` field instead.** Values: `north`, `south`, `east`, `west`. - `directions` (string[], optional): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. - `characteristics` (string[], optional): Property characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `alert_subtypes` (string[], optional): Alert subtypes. Values: `new`, `price_up`, `price_down`, `reserved`, `delisted`, `sold`. - `private` (boolean, optional): Whether to return alerts only from properties listed by a private individual, as opposed to an agent or a professional. - `auction` (boolean, optional): Whether to return alerts from auction property listings. - `bank` (boolean, optional): Whether to return alerts from bank property listings. - `new_development` (boolean, optional): Whether to return alerts from new development property listings. - `listing_agents` (string[], optional): Return alerts only for properties from specified agents. To find allowed agent names use the GET /api/v1/references/agents endpoint. - `with_agencies` (string[], optional): Return alerts only for properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `without_agencies` (string[], optional): Exclude alerts for properties from specified agencies, companies or sources. To find allowed agency names use the GET /api/v1/references/agencies endpoint. - `exclusive` (boolean, optional): Whether to return alerts exclusively from specific listings rather than from all related to the property listings. Can be passed only along with at least one of the fields: `private`, `with_agencies`, `without_agencies`. - `ref_numbers` (string[], optional): List of reference numbers from listings. - `has_phone` (boolean, optional): Whether to return alerts only from listings with or without `phone` number. - `has_email` (boolean, optional): Whether to return alerts only from listings with or without email. - `has_agency_name` (boolean, optional): Whether to return alerts only from listings with or without agency name. - `property_ids` (integer[], optional): List of property IDs. at most 100 items; ≥ 1. - `listing_ids` (integer[], optional): List of listing IDs. at most 100 items; ≥ 1. ## Example request Placeholders only: replace the token and the values with your own. ```bash curl -X POST "https://api.casafari.com/api/v1/listing-alerts/search" \ -H "Authorization: Bearer $CASAFARI_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "operation": "sale", "types": [ "apartment", "studio", "duplex", "penthouse" ], "location_ids": [ 2942, 1861, 1600 ], "conditions": [ "used", "very-good", "new" ], "statuses": [ "active", "reserved" ], "price_from": 150000, "price_to": 800000, "price_per_sqm_from": 2000, "price_per_sqm_to": 8000, "bedrooms_from": 1, "bedrooms_to": 3, "total_area_from": 30, "total_area_to": 130, "construction_year_from": 1950, "floors": [ "middle", "top" ], "views": [ "city" ], "directions": [ "west", "south" ], "characteristics": [ "balcony", "elevator", "parking" ], "private": false, "new_development": false, "has_agency_name": true, "has_email": false, "without_agencies": [ "Airbnb", "Casa.Sapo" ], "alert_date_from": "2021-09-01" }' ``` ## Responses ### 200 OK Type: `object[]`. - `count` (integer, optional) - `next` (string (uri), optional, nullable) - `previous` (string (uri), optional, nullable) - `results` (object, optional) - `alert_id` (integer, required): ID of the alert. - `listing_id` (integer, required): ID of the listing (ad). - `ref` (string, required): The reference ID of the listing. - `alert_type` (string, required): The type of the alert. Values: `sale_price`, `sale_status`, `rent_price`, `rent_status`, `new`. - `alert_subtype` (string, required): The subtype of the alert. Values: `new`, `price_up`, `price_down`, `reserved`, `delisted`, `sold`. - `old_value` (string, required): Value before change. - `new_value` (string, required): Value after change. - `alert_date` (string (date), required): Date when the alert occurred. - `alert_date_and_time` (string, optional, nullable): Date and time when the alert occurred. - `property_url` (string, optional, nullable): URL of the property in the CASAFARI website. - `listing_url` (string, optional, nullable): URL of the listing. Available only for currently active listings. - `listing_old_url` (string, optional, nullable): Old URL of the listing. Available only for currently inactive listings. - `listing_uid` (string, required): Unique ID of the listing on the source site. - `property_id` (integer, required): ID of the property to which the listing belongs. - `title` (string, required): Listing title. - `type` (string, required): Listing property type, as returned by the GET /api/v1/references/types endpoint. Values: `apartment`, `studio`, `duplex`, `penthouse`, `dachgeschosswohnung`, `etagenwohnung`, `erdgeschosswohnung`, `country_house`, `house`, `palace`, `townhouse`, `villa`, `country_estate`, `chalet`, `bungalow`, `family_house`, `reihenhaus`, `reihenendhaus`, `reihenmittelhaus`, `einfamilienhaus`, `zweifamilienhaus`, `landwirtschaftliche_betriebe`, `retail`, `office`, `industrial`, `warehouse`, `hotel`, `other_commercial`, `restaurant`, `werkstatt`, `plot`, `urban_plot`, `rural_plot`, `room`, `other`, `garage`, `parking`, `apartment_building`, `office_building`, `mix_use_building`. - `type_group` (string, required): Listing property type group, as returned by the GET /api/v1/references/types endpoint. - `location` (object, required): Information about property location. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `locations_structure` (object[], required): Information about all the parent locations (including property location) up to the country. - `location_id` (integer, required): Location ID, as returned by the POST /api/v1/references/locations endpoint. - `name` (string, required): Location name. - `administrative_level` (string, required): Location administrative level. - `zip_codes` (string[], optional): The location zip codes. default []. - `address` (string, required): Property address. - `zip_code` (string, required): The location zip code. - `cadastral_reference` (string, required): Cadastral reference of the estate. - `coordinates` (object, required): Property coordinates. - `latitude` (number, required): Latitude. - `longitude` (number, required): Longitude. - `condition` (string, required): Property condition, as returned by the GET /api/v1/references/conditions endpoint. Values: `used`, `ruin`, `very-good`, `new`, `other`. - `contacts_info` (object, required): Information about listing contacts. - `name` (string, required): The owner name. Only for FSBO listings. - `email` (string (email), required): The email contact. - `phone` (string, required): The phone contact. - `total_area` (integer, required): Total area. - `living_area` (integer, required): Living area. - `plot_area` (integer, required): Plot area. - `terrace_area` (integer, required): Terrace area. - `bedrooms` (integer, required): Number of bedrooms. - `rooms` (integer, required): Number of rooms. - `bathrooms` (integer, required): Number of bathrooms. - `features` (object, required): Property features, as returned by the GET /api/v1/references/features endpoint. - `floor` (string, required): Floor type. Values: `no_floor`, `ground`, `middle`, `top`. - `orientation` (string, required): Property view orientation. Values: `exterior`, `interior`. - `view` (string, required): View from the property. **This field is deprecated and will be removed in the next major update.** **Please, use `views` field instead.** Values: `water`, `landscape`, `city`, `golf`, `park`. - `views` (string[], required): List of views from the property. Values: `water`, `landscape`, `city`, `golf`, `park`. - `direction` (string, required): Cardinal direction the property faces. **This field is deprecated and will be removed in the next major update.** **Please, use `directions` field instead.** Values: `north`, `south`, `east`, `west`. - `directions` (string[], required): List of cardinal directions the property faces. Values: `north`, `south`, `east`, `west`. - `characteristics` (string[], required): Property characteristics. Values: `balcony`, `elevator`, `no_elevator`, `garage`, `garden`, `parking`, `storage`, `swimming_pool`, `terrace`, `rental_license`, `furniture`, `rented_out`, `life_annuity`. - `construction_year` (integer, required): Construction year. - `operations` (string[], required): Operation types for which listing property is available. Values: `sale`, `rent`. - `is_bank_property` (boolean, required): Whether the listing property is a bank property. - `is_auction_property` (boolean, required): Whether the listing property is an auction property. - `is_new_development_property` (boolean, required): Whether the listing property is a new development property. - `is_private_property` (boolean, required): Whether the property is listed by a private individual, as opposed to an agent or a professional. - `sale_status` (string, required): Current sale status of the listing. Values: `active`, `reserved`, `hold`, `sold`, `none`. - `sale_currency` (string, required): Sale price currency code. - `sale_price_base` (integer, required): Current sale price, in Euros. - `sale_price` (integer, required): Current sale price, in the currency of the listing (specified by the `sale_currency` field). - `sale_price_per_sqm` (number, required): Current sale price per square meter, in the currency of the listing (specified by the `sale_currency` field). - `sale_price_per_sqm_base` (number, required): Current sale price per square meter, in Euros. - `rent_status` (string, required): Current rent status of the listing. Values: `active`, `reserved`, `hold`, `rented`, `none`. - `rent_currency` (string, required): Rent price currency code. - `rent_price_base` (integer, required): Current rent price, in Euros. - `rent_price` (integer, required): Current rent price, in the currency of the listing (specified by the `rent_currency` field). - `rent_price_per_sqm` (number, required): Current rent price per square meter, in the currency of the listing (specified by the `rent_currency` field). - `rent_price_per_sqm_base` (number, required): Current rent price per square meter, in Euros. - `rent_period` (string, required): Rent period. Values: `day`, `week`, `fortnight`, `month`, `year`, `none`. - `agency_legal_id` (string, required): Agency legal identifier specified on the source. Only for France and its overseas territories(DROM and COM). - `agency` (string, required): The company that manages the listing. - `agent` (string, required): The agent that manages the listing. - `source_name` (string, required): The name of the source. - `description` (string, required): Listing description. - `thumbnails` (string[], optional): List of the thumbnail image URLs. - `pictures` (string[], optional): List of the original picture image URLs. - `created_at` (string (date-time), required): Date and time when the alert was created (UTC). - `created_at_with_photos` (string (date-time), required): Date and time (UTC) when the alert was created and its photos were processed. Can be `null` if photo processing has not finished yet. If the listing has no photos but the system has finished the processing, this field will contain its date and time. - `updated_at` (string (date-time), required): Date and time when the alert data was updated (UTC). - `energy_certificate` (string, required): Energy certificate classification that attests to the energy efficiency of a listing. **This field is deprecated and will be removed in the next major update.** **Please, use `energy_rating` field instead.** - `energy_rating` (string, required): Energy rating that attests to the energy efficiency of a listing. - `heating_type` (string, required): Type of heating. - `available_from` (string (date), required): The date the listing property becomes available for occupancy. The start of the availability window. - `available_to` (string (date), required): The date the listing property stops being available. The end of the availability window. Example from the API description (long arrays shortened): ```json { "count": 79, "next": "https://api.casafari.com/v1/listing-alerts/search?limit=50&offset=50", "results": [ { "alert_id": 412269711, "listing_id": 110358519, "title": "Apartamento T2 em Santa Engracia", "ref": "ID-124021076-47", "alert_type": "sale_price", "alert_subtype": "price_down", "old_value": "549000", "new_value": "545000", "alert_date": "2021-10-24", "alert_date_and_time": "2021-10-24T05:37:09", "created_at": "2021-10-24T05:38:53.273581", "created_at_with_photos": "2021-10-24T05:43:27.622175", "updated_at": "2021-04-05T17:47:19.191211", "property_url": "https://www.casafari.com/home-sale/property-51277418", "listing_url": "https://www.idealista.pt/imovel/31407575/", "listing_uid": "1054046", "property_id": 51277418, "type": "apartment", "type_group": "apartment", "location": { "location_id": 28649, "name": "Santa Engrácia", "administrative_level": "Localidade", "zip_codes": [] }, "locations_structure": [ { "location_id": 499, "name": "Portugal", "administrative_level": "País", "zip_codes": [ "1200-224" ] } ], "address": "", "zip_code": "80804", "cadastral_reference": "2181605VK4728A0001TA", "coordinates": { "latitude": 38.7194, "longitude": -9.12209 }, "condition": "used", "contacts_info": { "phone": "215551538" }, "total_area": 130, "living_area": 128, "plot_area": 0, "terrace_area": 15, "bedrooms": 3, "rooms": 0, "bathrooms": 2, "features": { "floor": "middle", "views": [ "city" ], "directions": [ "west" ], "characteristics": [ "balcony" ] }, "construction_year": 2015, "operations": [ "sale" ], "is_bank_property": false, "is_auction_property": false, "is_new_development_property": false, "is_private_property": false, "sale_status": "active", "sale_currency": "EUR", "sale_price": 545000, "sale_price_base": 545000, "sale_price_per_sqm": 4192, "sale_price_per_sqm_base": 4192, "rent_status": "none", "rent_currency": "EUR", "rent_price": 0, "rent_price_base": 0, "rent_price_per_sqm": 0, "rent_price_per_sqm_base": 0, "rent_period": "none", "agency_legal_id": "402016653", "agency": "Helena Almeida Pires", "agent": "", "source_name": "Idealista", "description": "O apartamento é composto de sala de estar e jantar ampla, com janelas de vidro duplo que dão enorme luminosidade, ao ambiente.", "thumbnails": [ "https://st2.retelligence.co/c/2875/4/7f/5a0fc6ebf8e4e41d062342a29b50647f350.jpg" ], "pictures": [ "https://media.casasapo.pt/Z1140x855/Wnone/S5/C2729/P20091734/Tphoto/ID56933201-0000-0500-0000-00000d1ffcdc.jpg" ], "energy_certificate": "B", "energy_rating": "B", "heating_type": "Central heating", "available_from": "2026-07-01", "available_to": "2027-06-30" } ] } ``` ### 400 Bad Request Type: `object`. - `errors` (object, optional): Description of the errors encountered. ### 401 Unauthorized Type: `object`. - `detail` (string, optional): Description of the error encountered. ### 403 Forbidden Type: `object`. - `detail` (string, optional): Description of the error encountered.