Preview Property Search
preview_property_searchRead-only
What it returns
A free preview of a property-database search: count (how many properties match the filters) and cost (the credits the full search would charge). This call never charges credits.
This is the mandatory safety step before run_property_search. The charged search costs 1 credit per matching property, so a broad filter set can cost thousands of credits. Always preview here, tell the user the count and cost, and get an explicit yes before running the paid search.
When to use it
ALWAYS before
run_property_search, to size and price the result set.To tighten filters (narrow the location, add a price band / condition / ROI floor) until the count and cost fit the user's budget.
To confirm a search returns anything before spending.
Required filters
Every search needs a location (a city, county, or ZIP — NEVER a whole state: state-wide queries time out, this free preview included), a property_status, AND at least one investment filter (price range, property type, condition, investment-potential grade, ROI range, …). The investment-filter rule keeps results pertinent and cost-effective. It can be waived with allow_location_only=true, but a location-only search in a dense metro can match thousands of properties — check the cost first.
Pricing
Free — 0 credits. Only run_property_search charges.
Errors
Status | Meaning |
400 | Required filters missing — the |
401 | Authentication failed. |
402 | No active subscription. |
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"location": "<location>",
"property_status": "<property_status>"
},
"name": "preview_property_search"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Sold-search only: latest sold date (ISO-8601, `YYYY-MM-DD`). | |
| dom | No | Days-on-market ceiling (for-sale only): only listings listed within the last N days. | |
| from | No | Sold-search only: earliest sold date (ISO-8601, `YYYY-MM-DD`). | |
| auction | No | Which catalogue to search. OMIT it to search MLS listings — the default, which hides auction-only homes. `off_mls` = only off-MLS auction homes: foreclosure and bank-owned auctions on Auction.com, Xome and Hubzu with no MLS listing. The two are separate searches, exactly as the Homesage portal's market switch is (MLS = omitted, Off-MLS = `off_mls`): an MLS listing's ROI, Spread, LP/ARV and grade are worked out at its list price, and an off-MLS home's at its expected winning bid (the price such homes typically sell for at auction, or the published bid when higher). Never merge, rank or compare the two in one list; if the user wants both, run one search for each and present two lists. Off-MLS homes are live auctions: send `property_status=active` with them, and use `auction_within_days` rather than `dom`, since no auction site publishes a listing date. On an off-MLS auction home the other filters read its auction numbers: `price_min`/`price_max` read the published bid (the current bid, else the opening bid) and a home with no published bid drops out of them; `roi_min`/`roi_max` read the ROI at the expected winning bid; `investment_potential_grades` and `investment_potential_min` read its auction Investment Potential score (that ROI, held to 0-100); `lpfp_min`/`lpfp_max` read LP/ARV at the expected winning bid; `gap_min`/`gap_max` read the spread at the expected winning bid over the published bid, so a home with no published bid drops out of them. `cap_rate_min`/`cap_rate_max` and `cash_on_cash_min`/`cash_on_cash_max` read its cap rate and cash-on-cash at its max bid (the yield if you win the auction at the max bid, paying cash), and a home with no max bid or no rent drops out of them. `property_condition` and `pfs_min`/`pfs_max` EXCLUDE off-MLS auction homes, so combining either with `auction=off_mls` returns no results: they have no seller-motivation score, and the condition filter reads the listing's condition column, which is empty on them. An off-MLS home whose auction listing has inside photos is graded from them, and its row says so in its `auction` block (`condition`, with `condition_basis: "inside_photos"` and `condition_photos`, the number of photos); every other one has `condition: null` and `condition_basis: "assumed"`. | |
| gap_max | No | Maximum Value Gap percentage. | |
| gap_min | No | Minimum Value Gap as a PERCENTAGE (`15` = 15%): the spread between the full-potential value and the list price, relative to the list price. FOR-SALE ONLY: sold listings carry no value for it, so combining this with `property_status=sold` returns no results. | |
| pfs_max | No | Maximum Seller Motivation Score (1–100). | |
| pfs_min | No | Minimum Seller Motivation Score — the Price Flexibility Score, 1–100: how much negotiating room the asking price has, higher = more flexible. FOR-SALE ONLY: sold listings carry no value for it, so combining this with `property_status=sold` returns no results. | |
| roi_max | No | Maximum projected ROI percentage. | |
| roi_min | No | Minimum projected ROI, as a percentage (e.g. `15` = 15%). | |
| location | Yes | A JSON-encoded array of one or more area objects. City: `{"type":"city","city":"Austin","state_code":"TX"}`; county: `{"type":"county","county":"Travis County","state_code":"TX"}`; ZIP: `{"type":"postal_code","zip_code":"78704","state_code":"TX"}`. State-wide scope is not supported — a state-level area times out instead of returning. When the user asks about a whole state or a huge metro, pick the specific city, county, or ZIP that best serves their goal (or run a few targeted searches) yourself; never surface a 'narrow your area' error to the user. Several area objects in one array are searched together, so a multi-ZIP or multi-city search is one preview and one charged call. | |
| lpfp_max | No | Maximum LP/ARV percentage (`85` = listed at no more than 85% of full potential). | |
| lpfp_min | No | Minimum LP/ARV — the list price as a PERCENTAGE of the property's full-potential (after-repair) value, 1–100, lower is better (`80` = listed at 80% of full potential). FOR-SALE ONLY: sold listings carry no value for it, so combining this with `property_status=sold` returns no results. | |
| price_max | No | Maximum price in USD. | |
| price_min | No | Minimum price in USD (list price for for-sale, sold price for sold). | |
| sale_type | No | Pipe-delimited auction sale types. One or more of: `foreclosure` (trustee and foreclosure sales), `bank_owned` (REO — the lender already owns the home), `other` (short sales, private sellers, and sales of unknown type). Use with `auction=off_mls`. | |
| cap_rate_max | No | Maximum capitalisation rate as a percentage. Use a negative value (e.g. `-1`) to search for cash-flow-negative properties. | |
| cap_rate_min | No | Minimum capitalisation rate as a PERCENTAGE (`6.5` = 6.5%), computed at all-cash, 20% down, 4.5%, 30-year assumptions. Negative values are valid and meaningful: a property with high HOA or tax costs genuinely returns a negative cap rate. Only properties with a verified rent carry this metric — about 35% of for-sale listings — and the rest are absent from the results rather than treated as zero. FOR-SALE ONLY: sold listings never carry it, so combining this with `property_status=sold` returns no results. | |
| property_type | No | Pipe-delimited property types. One or more of: `detached|townhouse|apartment|multi family|other`. | |
| also_at_auction | No | Set `true` to keep only MLS listings that are ALSO up for auction on Auction.com, Xome or Hubzu — for example a bank listing a repossessed home with an agent while auctioning it at the same time. A filter on the MLS search: use it with `auction` omitted. | |
| property_status | Yes | Listing status to search. `active`/`pending` search live for-sale listings; `sold` searches historical sales (enables the `from`/`to` date range); `any` = active + pending. | |
| cash_on_cash_max | No | Maximum cash-on-cash return as a percentage. | |
| cash_on_cash_min | No | Minimum cash-on-cash return as a PERCENTAGE (`4` = 4%), at the same default assumptions as `cap_rate_min`. Negative values are valid. Only properties with a verified rent carry this metric — about 35% of for-sale listings — and the rest are absent from the results rather than treated as zero. FOR-SALE ONLY: sold listings never carry it, so combining this with `property_status=sold` returns no results. | |
| monthly_rent_max | No | Maximum estimated monthly rent in whole USD. | |
| monthly_rent_min | No | Minimum estimated monthly rent in whole USD. Properties with no rent estimate are excluded. | |
| rent_to_price_max | No | Maximum monthly rent as a ratio of price (`0.02` = 2%/mo). | |
| rent_to_price_min | No | Minimum monthly rent as a RATIO of price — `0.007` is 0.7%/mo, not 0.7. Note the contrast with `cap_rate_min` and `cash_on_cash_min` below, which are percentages. | |
| property_condition | No | Pipe-delimited condition grades (Homesage.ai ML-derived). One or more of: `excellent|good|outdated|very poor|poor|unlivable`. | |
| published_bid_only | No | Set `true` to leave out auction homes whose opening bid is not published yet (it keeps only homes with a price above zero). Use with `auction=off_mls`. | |
| allow_location_only | No | Set `true` to waive the investment-filter requirement and search by location + status alone. Use with care — location-only searches can match thousands of properties. Location and status remain required. | |
| auction_within_days | No | Auction-date window: only homes whose next auction falls between today and today + N days — `7`, `30` or `90`. A home with no upcoming auction date does not match. Use with `auction=off_mls`. | |
| investment_potential_min | No | Minimum Investment Potential score (0–100), for-sale only. Ignored when `investment_potential_grades` is also sent — the grades win — so send one or the other. | |
| investment_potential_grades | No | Pipe-delimited investment-potential grades (for-sale only). Codes: `excel` (ROI ≥ 35%), `high` (25–35%), `med` (15–25%), `low` (5–15%), `noPot` (< 5%). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||