# How do I look up one property and see every price and status change?

> **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).

Fetch the property with `GET /api/v1/properties/search/{property_id}` in Casafari's Property Sourcing REST API. Each record merges every advertisement of one property and carries its full history: every price change, status change, appearance and removal, with dates, in `sale_price_history` and `rent_price_history`. First find the id from a portal or agency ad id, or from a reference number.

Products: [Property Sourcing](/docs/property-sourcing), [References](/docs/references).

## Short answer

Casafari collects property advertisements from agency websites and portals in 16 countries. It structures, cleans and deduplicates them, then merges every advertisement of a property into one record. That record carries the property's full history: every price change, status change, appearance and removal, with dates. Prices over time are in `sale_price_history` and `rent_price_history`.

You fetch the record over the REST API with [`GET /api/v1/properties/search/{property_id}`](/docs/rest/property-sourcing/get-property-by-id-v1), part of [Property Sourcing](/docs/property-sourcing). [The property graph](/docs/property-graph) explains how the record is built.

## Steps

### Get a token: `POST /login`

1. Send the account's `email` and `password` as JSON to `POST https://api.casafari.com/login`. The response holds an `access_token` and a `refresh_token` (JWT). Send `Authorization: Bearer <access_token>` on every call. Renew the token with `GET /refresh-token` when it expires.

### Find the property id: from a portal or agency ad id with `POST /api/v1/properties/match-by-listings`, or by `ref_numbers` with `POST /api/v2/properties/search`

2. If you hold a portal or agency ad id, send it in `listing_ids` to [`POST /api/v1/properties/match-by-listings`](/docs/rest/property-sourcing/get-property-by-listing-ids-v1). The operation resolves the ad to the property it belongs to.
3. If you only hold the agency's own reference number, send it in `ref_numbers` to [`POST /api/v2/properties/search`](/docs/rest/property-sourcing/search-properties-v2). Add `location_ids` to narrow the search.

### Fetch: `GET /api/v1/properties/search/{property_id}`

4. Call the operation with the property id from step 2 or 3. It returns the property and its history.

### Read `sale_price_history`, `rent_price_history` and the status fields

5. Read `sale_price_history` for asking prices on the sales market and `rent_price_history` for the rental market. Each change carries its date.
6. Read the status fields for the property's current state on each market. In Casafari property records these are `sale_status` and `rent_status`. The [operation's reference page](/docs/rest/property-sourcing/get-property-by-id-v1) has the full response schema.

## Example

A buyer's agent in Lisbon has the id of a portal ad for a flat. They want to know how long it has been offered and at what prices.

```http
POST https://api.casafari.com/login
Content-Type: application/json

{ "email": "agent@example.com", "password": "<password>" }
```

```http
POST https://api.casafari.com/api/v1/properties/match-by-listings
Authorization: Bearer <access_token>
Content-Type: application/json

{ "listing_ids": ["<portal ad id>"] }
```

```http
GET https://api.casafari.com/api/v1/properties/search/<property_id>
Authorization: Bearer <access_token>
```

The condensed record below shows field names only. Values are elided. The exact shape of each history entry is on the [reference page](/docs/rest/property-sourcing/get-property-by-id-v1) and in the public OpenAPI description at https://docs.api.casafari.com/openapi.json.

```json
{
  "property_id": "<property_id>",
  "sale_status": "...",
  "rent_status": "...",
  "sale_price_history": ["..."],
  "rent_price_history": ["..."]
}
```

## How to read the result

Read the history in date order.

- **First appearance:** tells you how long the property has been offered.
- **Each price change:** shows the direction and size of the move.
- **Removals followed by reappearances:** show whether the property was withdrawn and offered again. This answers the question "was this home on the market before?"

A long history with several cuts is negotiation leverage for a buyer. For a valuer, lender or due-diligence team, the same history is a dated record of how the market has treated the property.

### Statuses: active, reserved, hold, sold, rented

The graph records each status change with its date:

- On the sales market a property can be active, reserved, on hold or sold.
- On the rental market it can be active, reserved, on hold or rented.

Read a status as the property's state on the market as the graph observed it from the advertisements.

### Several agencies, one record: the agencies linked to the property

When several agencies and portals advertise the same property, Casafari recognises them as one property. It keeps one record that links the advertisements, agencies, agents, location and history. You therefore read one history, not one per advertisement. Agency names match the values from [`GET /api/v1/references/agencies`](/docs/rest/references/get-agencies-v1).

## Limits

Property Sourcing is REST only and for Casafari client accounts. It is not offered over MCP. For Property Sourcing, self-serve access for new users is coming soon.

The sources give no figures for pricing, quotas, rate limits, refresh frequency or SLAs. Ask Casafari at https://www.casafari.com/.

### Client account only; MCP does not search or fetch properties

The Casafari MCP server has no tool that searches or fetches properties. A request such as "show me the price history of property 123456" made to an assistant connected over MCP cannot be answered from Property Sourcing. Your own code, or an agent with a REST token, calls the operations above. See [Can I search properties over Casafari MCP?](/docs/faq/properties-over-mcp).

### History covers what the graph observed since the property first appeared

The history starts when the property first appeared in the sources Casafari collects. A property never advertised in those sources has no history in the graph. Changes made before its first appearance are not recorded. The history shows asking prices and statuses on the market; it does not tell you the price a buyer finally paid. More: [Does Casafari keep price and status history?](/docs/faq/price-and-status-history) and [How do I look up one property and its price history?](/docs/faq/example-property-lookup).

## Questions

### Can I look up a property over MCP?

No, property lookup is not offered over the Casafari MCP server. Property Sourcing, including `GET /api/v1/properties/search/{property_id}`, is a REST product for Casafari client accounts. The MCP server's tools cover Comparables & Valuation, Area Insights and AgentGraph AI. An agent can still call the REST operations directly once it holds a bearer token from `POST /login` or an API client.

### What if the same property was advertised at different prices by two agencies?

It is still one property record, because Casafari recognises the same property advertised by several agencies and portals as one and merges every advertisement into that record. The record keeps every price change with its date. The sources do not describe how two asking prices that differ at the same moment are reconciled; check the operation's reference page for the fields returned.

### Can I see which agencies advertised it?

Yes, the property record links the advertisements, agencies and agents behind the property, as well as its location and history. Agency names correspond to the values returned by `GET /api/v1/references/agencies`. The exact response fields for the fetch operation are on its reference page at /docs/rest/property-sourcing/get-property-by-id-v1 and in the public OpenAPI description.

### Can I get the history for every property in an area in bulk?

For bulk delivery, see Data Export at /docs/data-export, which describes bulk delivery and the fields of each entity, including the Property entity. Over the REST API you can search an area with `POST /api/v2/properties/search` and fetch each property by id. The sources publish no terms, pricing or limits for bulk delivery; ask Casafari at https://www.casafari.com/.

Related: [Resolve client-forwarded links to one property record](/docs/property-sourcing/use-cases/resolve-client-forwarded-links).

All use cases: [Use cases](/docs/use-cases#property-data).