Preview a property-database search — free match count + credit cost

GET /api/workspace/search/count/

Free

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 missing array names them (location, property_status, and/or investment_lens).
401	Authentication failed.
402	No active subscription.

Parameters

location (query, required) — 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.
property_status (query, required) — Listing status to search. active/pending search live for-sale listings; sold searches historical sales (enables the from/to date range); any = active + pending.
price_min (query) — Minimum price in USD (list price for for-sale, sold price for sold).
price_max (query) — Maximum price in USD.
property_type (query) — Pipe-delimited property types. One or more of: detached|townhouse|apartment|multi family|other.
property_condition (query) — Pipe-delimited condition grades (Homesage.ai ML-derived). One or more of: excellent|good|outdated|very poor|poor|unlivable.
investment_potential_grades (query) — Pipe-delimited investment-potential grades (for-sale only). Codes: excel (ROI ≥ 35%), high (25–35%), med (15–25%), low (5–15%), noPot (< 5%).
roi_min (query) — Minimum projected ROI, as a percentage (e.g. 15 = 15%).
roi_max (query) — Maximum projected ROI percentage.
monthly_rent_min (query) — Minimum estimated monthly rent in whole USD. Properties with no rent estimate are excluded.
monthly_rent_max (query) — Maximum estimated monthly rent in whole USD.
rent_to_price_min (query) — 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.
rent_to_price_max (query) — Maximum monthly rent as a ratio of price (0.02 = 2%/mo).
cap_rate_min (query) — 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.
cap_rate_max (query) — Maximum capitalisation rate as a percentage. Use a negative value (e.g. -1) to search for cash-flow-negative properties.
cash_on_cash_min (query) — 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.
cash_on_cash_max (query) — Maximum cash-on-cash return as a percentage.
dom (query) — Days-on-market ceiling (for-sale only): only listings listed within the last N days.
from (query) — Sold-search only: earliest sold date (ISO-8601, YYYY-MM-DD).
to (query) — Sold-search only: latest sold date (ISO-8601, YYYY-MM-DD).
allow_location_only (query) — 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.

Responses

200 — Match count and the credit cost of running the full search. No charge.
400 — Required filters missing. The missing array lists the unmet obligations. Costs 0 credits.
401 — Authentication failed — missing or invalid credential. Costs 0 credits.
402 — No active subscription. Costs 0 credits.