Listing history
GET /v1/listings/history/{uprn}Every marketing snapshot for a property: asking price over time, price reductions, days listed, status changes, agent, image count and whether it had a floor plan.
Same call over MCP
Listing history for a propertylisting_historyAuthenticate with an API key from the API & MCP Hub. The same call is available as an MCP tool at the same price.
Reference
What GET /v1/listings/history/{uprn} returns
price_trajectory appears only when at least two snapshots carry a price. No listing at all is a real answer, not a failure — a property sold off-market or never advertised has none.
UK only.
Inputs
Before you call it
- uprn
- A UPRN is the Unique Property Reference Number every UK address carries. Narrow the address with address_autocomplete, which is free, then address_resolve returns the UPRN for 8 credits. property_summary and address_by_postcode return UPRNs too.
Request
Calling GET /v1/listings/history/{uprn}
curl "https://api.marketcode.ai/v1/listings/history/200003443835" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"Send your API key as a Bearer token. Every response carries credits_charged and credits_remaining.
Inputs
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| uprn | Path | integer | Yes | Property UPRN |
Response
What GET /v1/listings/history/{uprn} returns for a real request
curl "https://api.marketcode.ai/v1/listings/history/200003443835" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"{
"uprn": "<string>",
"listings": [],
"count": 0,
"price_trajectory": null,
"note": "<string>",
"credits_charged": 0
}Shape only. This call returns licensed records, so the keys are real and every value is a placeholder of its type.
Response
Response fields
| Field | Type |
|---|---|
| uprn | string |
| listings | array |
| count | integer |
| price_trajectory | null |
| note | string |
| credits_charged | integer |
Fields observed in the example response above; a field the example did not exercise is not listed.
Price and licence
What it costs, and where the data comes from
Listing history costs 3 credits per successful call over MCP and over REST, and the two surfaces share one credit balance.
The price covers licensed records in the response, from Property portals. A call that fails is not charged.
Credits are granted on sign-up and bought in packs; the pricing page lists every call.
Sources
- Property portals
Sale and lettings listings
Collected from publicly marketed listings · Great Britain
Related
Endpoints used with Listing history
- Resolve an address to a UPRN8 credits
address_resolveResolve free-text address to canonical record (UPRN for UK).Same product - Property summary4 credits
property_summaryOne-call summary of a property: what it is, what building it belongs to,Same product - Full valuation with back-seriesFree
valuation_fullFull valuation block for a property: the value and its range, a monthlySame product - Comparable properties6 credits
property_compsComparable properties in the same building or block, with missingSame product - Registered sales for a propertyFree
transactions_by_uprnAll HMLR Price Paid records joined to this UPRN, newest first.Same product - House price index seriesFree
market_index_seriesThe published house-price INDEX for one postcode district or local authority: the level per month (base period = 100), the forecast tail flagged, and provenance saying how the index was built.Same product
Glossary
Terms used here
- Asking price and asking-to-sold ratio: The price a property is marketed at, as against the price it sells for; asking leads sold by months and includes what never sells, and the ratio between them is a temperature gauge.
- Days on market: How long a listing has been marketed; MarketCode reports the age of live stock and the days to completion on matched sales, and is explicit that a true days-to-sale is not observable from portals.
FAQ
Questions about Listing history
How much does `listing_history` cost?
+
Listing history costs 3 credits per successful call over MCP and over REST, and the two surfaces share one credit balance. The price covers licensed records in the response, from Property portals. A call that fails is not charged.
Do I need to resolve the address first?
+
Yes. listing_history takes a UPRN, not an address. Start with address_autocomplete (free) to narrow the address, then address_resolve (8 credits) to get the UPRN. An assistant with the MarketCode skills installed does both steps on its own.
How do I authenticate?
+
Send your API key as a Bearer token in the Authorization header. Keys are created in the API & MCP Hub, shown once and revocable. Every response carries the credits charged and your remaining balance.
Is there an MCP version?
+
Yes. The listing_history tool on the MarketCode MCP server is the same call at the same price, signed in with OAuth rather than a key, so Claude, ChatGPT, Codex and Cursor can run it in a conversation.
Where does the data come from?
+
Read from Property portals listings. Coverage is the UK.
Can I store or republish the results?
+
The response includes records we license from Property portals. Use them in your own analysis, reports and products; bulk redistribution of the raw records or building a competing dataset from them is not covered. Ask us if you need a redistribution licence.
Does `listing_history` change anything?
+
No. The tool is annotated read-only on the server, so it never writes to your data or ours and an assistant can call it without a confirmation step.
Try Listing history on a real address.
30-minute call. We'll provision a key and walk through the endpoint on your use case.