Homesage.ai

## What it returns A time-series of monthly AVM estimates for a property over the last 5 years. Designed to plot value-over-time charts and detect inflection points (renovation, neighborhood revaluation, market cycle). ## When to use it - Render a value-history chart on a property detail page. - Detect properties whose value diverged from their neighborhood trend. ## Pricing 1 credit. ## FAQ ### How far back does the history go? Up to 60 months. New construction has shorter history. Pre-MLS-era properties may have gaps.

get_home_value_history

## What it returns An **Investment Potential** score for a US residential property — a single `investment_potential` value on a 0-100 scale, where higher is better. Designed as a first-pass filter for investor screening. The value is `null` when a score cannot be computed for that property. ## When to use it - Rank a watchlist of properties by overall investment quality. - Power a 'top opportunities in your market' feed. ## Pricing 3 credits. ## FAQ ### Is the score a percentage? No — it's a 0-100 composite index. Higher = better. ### Why is the score `null`? A score could not be computed for that property. Use `current-estimate` and `comps` to assess it directly. ### Does it account for my financing assumptions? No — it's a property-level score, not deal-specific. For deal-level returns, use `flip-return` or `rental-long-term`.

get_investment_potential

## What it returns Projected long-term rental income — monthly rent band, vacancy assumption, gross operating income, net operating income after standard expense ratios, and capitalization rate vs. the AVM. Built from MLS-comparable rentals in the same micro-market. ## When to use it - Underwrite buy-and-hold rental candidates. - Compute cap rates across a watchlist. ## Pricing 5 credits. ## FAQ ### What's included in the expense assumption? Property management (8%), maintenance (5%), vacancy (5%), insurance, property tax. Mortgage cost is NOT included — these are pre-debt-service numbers (NOI).

get_long_term_rental

## What it returns A composite **Market Outlook score** (0-100) classifying a ZIP code as a buyer's market (<40), balanced (40-60), or seller's market (>60). Built from a hybrid weighted model — 40% macro market indicators (market-heat index and forecasts), 40% Homesage.ai absorption-rate analytics, and 20% live market signals when available. Includes 1/3/6-month forecasts, days-on-market velocity, active/sold/pending counts, and a per-signal breakdown. ## When to use it - Render a market-context widget on a property report. - Power a 'best markets to buy' / 'best markets to sell' ranking. - Inform pricing-strategy recommendations. ## Pricing 2 credits. ## FAQ ### What if live market data is unavailable? The live-signal weight rebalances to the macro and Homesage.ai components (50% / 50%). The response's `weights_used` field reflects the actual weights applied. ### Why ZIP-level instead of city or county? ZIP is the smallest unit that all three sources support consistently. For city/county roll-ups, query multiple ZIPs and aggregate.

get_market_outlook

## What it returns Mortgage and lien records for a US property — current and historical mortgages, lien summary, involuntary liens, pre-foreclosure status, and data quality metadata. Sourced from a county-records aggregator and cached for 7 days; cached responses cost 0 credits. ## Performance **Fresh lookups are slow — use a 60-second client timeout and cache responses (we cache for 7 days; cached reads are fast and free).** ## When to use it - Identify distressed properties (high lien-to-value ratio, pre-foreclosure). - Pre-screen wholesale outreach lists for owner-equity position. - Disclose lien position to a buyer or lender. ## Pricing 5 credits per **fresh** request. Cached responses (within 7 days of the prior fetch for the same address) cost 0 credits. ## FAQ ### Is this real-time? No — mortgage recordings post to county records with days-to-weeks lag. The 7-day cache reflects that natural cadence. ### What if the property has no mortgage? Returns an empty mortgages array and the lien summary reflects equity-only status. Still counts as 5 credits (the call ran).

get_mortgage_lien_analysis

## What it returns A **Price Flexibility Score (PFS)** for an active listing — an estimate of how much price-negotiation room it has, derived from days-on-market, price-change history, comparable activity, and seasonal demand. Higher score = more flexible (buyer can negotiate down more). ## When to use it - Suggest a target offer percentage to a buyer. - Sort lead lists by negotiation opportunity. - Trigger an alert when a watched property's PFS climbs. ## Pricing 2 credits. ## FAQ ### Does PFS work on sold properties? PFS scores a live asking price, so it returns a 400 error (`{"error": "Property is sold"}`) only when the property's current listing status is exactly `sold`. A recently-sold property whose status is anything else (`for_sale`, `off_market`, `pending`, ...) still returns a normal score — so a property can show up in `sold-by-zip` results and still be scorable here. ### Is PFS the same as AVM? No. AVM estimates *what the property is worth*. PFS estimates *how movable the asking price is* — orthogonal questions.

get_price_flexibility_score

## What it returns An **AI condition assessment** for a US residential property — overall condition category (Excellent/Good/Fair/Poor), confidence score, per-room breakdown when photos are available, and any flags (water damage, deferred maintenance signals). Built from a computer-vision pipeline on the listing's photo set. ## When to use it - Filter MLS feeds to move-in-ready vs. fixer candidates. - Adjust AVM expectations based on actual condition. - Pre-screen photos to skip a manual review pass. ## Pricing 2 credits. ## FAQ ### What model is used? A multimodal AI vision pipeline; specific models aren't disclosed. Outputs are described in domain terms (`Excellent`, `Good`, …) so the contract is stable across model swaps. ### Does it work on listings without photos? No — returns `null` overall and a low confidence score. To supply your own photos for a more accurate assessment, use `property-condition-custom-photos`.

get_property_condition

## What it returns Full property record for a single US residential property — address, coordinates, listing status and price, AVM-estimated value, size, days on market, building/lot/parking/interior breakdown, listing-office details, recent property history, and nearby school ratings. Sourced from a national listing graph + Homesage.ai's AVM, hydrated on the first call per property and cached. ## When to use it - Render a property-detail page in your UI. - Enrich a CRM lead record with the latest listing status and AVM. - Cross-check a third-party AVM against Homesage.ai's. - Look up listing-office contact info from a property address. ## Pricing **2 credits per successful call.** `null` returns from missing source data still cost 2 credits because the upstream call still ran. `404`/`401`/`402` cost 0 credits. ## Errors | Status | Meaning | |---|---| | 400 | Neither `property_address` nor `property_id` provided, or `property_id` is not valid base64. | | 401 | Authentication failed. | | 402 | No subscription, or out of credits. | | 404 | The autocomplete suggestion didn't match a real listing. Response includes `did_you_mean` suggestions. | ## FAQ ### What's the difference between `info` and `updated-info`? `info` is the fast lookup and may serve recently stored data. `updated-info` always returns the freshest available record (slower). Use `updated-info` when stale data matters — pricing decisions, just-listed alerts, post-sale follow-ups. ### Why is `listing_price` `null`? The property is not currently listed for sale. `estimated_value` (AVM) is still populated when available. ### Can I look up by `property_id` instead of address? Yes — pass `property_id` as a base64-encoded string. Use the `id` field returned by `auto-complete`. ### How fresh are school ratings? Refreshed annually from national school-ratings data.

get_property_info

## What it returns An aggregate estimated renovation cost for a property, plus the sqft basis and the per-sqft cost-of-construction model used. For a room-by-room breakdown with material/labor split, use `renovation-cost-breakdown` instead. ## When to use it - Quick screening of fix-and-flip cost before detailed underwriting. - Feed into `flip-return` for an end-to-end deal-level projection. ## Pricing 5 credits. ## FAQ ### What renovation scope is assumed? A standard mid-grade refresh. Use `renovation-cost-breakdown` for explicit room/scope control.

get_renovation_cost

## What it returns Projected return analysis assuming a standard renovation is performed: pre-renovation AVM, projected post-renovation ARV (After Repair Value), renovation cost estimate (see `renovation-cost` for a breakdown), and net return + ROI percent. ## When to use it - Evaluate buy-and-fix-up opportunities. - Compare renovation vs. cosmetic-only strategies on a single property. ## Pricing 3 credits. ## FAQ ### What renovation scope is assumed? A mid-grade full-interior refresh. For a custom scope, use `renovation-cost` with explicit room-level inputs. ### How is ARV calculated? From renovated comps in the same micro-market, adjusted for size and condition delta. See `comps` for the underlying comparable set.

get_renovation_return

## What it returns Projected short-term rental performance — nightly rate band, expected occupancy, monthly gross income, net of typical expense ratios. Built from STR comparables in the same micro-market. ## When to use it - Evaluate STR opportunities for buy-and-host investors. - Compare LTR vs. STR income on the same property. ## Pricing 5 credits. ## FAQ ### Does it account for local STR regulations? No — markets with STR bans/caps may produce projections that aren't operationally achievable. Verify local rules before underwriting.

get_short_term_rental

## What it returns Two coupled analyses in one call: 1. **Solar Potential** — 20-year cost projection, payback timeline, energy coverage percentage, federal/state incentive estimate. 2. **Roof Condition** — AI roof condition score (0-10), condition category, material identification, damage indicators, and risk assessment, from AI analysis of aerial imagery. ## When to use it - Pre-screen properties for solar installation viability. - Underwrite roof replacement cost for an investor offer. - Add a solar-readiness flag to a property report. ## Performance **This is an expensive, slow endpoint — use a 90-second client timeout and cache responses.** ## Response shape The response shape varies with the optional query parameters: - `detailed=true` — adds the raw `solar_potential.data` blob and includes both `roof_image_url` and `roof_image_base64` in `roof_condition.imagery`. - `agent=false` — sets `roof_condition.analysis` to `null` (skips the AI roof analysis). If the roof image fails to upload to storage, `roof_condition.imagery` contains `roof_image_base64` (raw base64 PNG) instead of `roof_image_url`. Individual entries in `solar_layers` may be missing if a particular data layer was unavailable for the address. ## FAQ ### Why is `agent=true` the default? Without it, the roof condition section is skipped (you get solar potential only). The AI roof analysis is the expensive part but it's what makes the endpoint useful — leave it on unless you specifically need solar-only. ### What if the building isn't covered? Returns a clear error indicating imagery unavailable. Charges 0 credits in that case.

get_solar_analysis

## What it returns Just the **count** of residential properties sold in a ZIP within the last 365 days. Same dedup + recency rules as `sold-by-zip`, but only the integer count — useful when you don't need the property details and want to minimize cost. ## When to use it - Display market velocity in a header widget (no need to render rows). - Drive a chart of monthly sales trend across many ZIPs cheaply. - Pre-check whether a ZIP has enough comp activity before calling `sold-by-zip`. ## Date range By default the endpoint returns the full trailing 365 days. Pass `start_date`, `end_date`, or both (`YYYY-MM-DD`) to narrow that to a specific window — for example one calendar month at a time instead of re-pulling the whole year on every poll: ``` ?zip=95630&start_date=2026-08-01&end_date=2026-08-31 ``` Both bounds are optional and inclusive, and both are independent: pass only `start_date` for an open-ended window, or only `end_date` to cut off recent sales. Passing neither leaves existing behaviour unchanged. Either bound must fall within the last 365 days. An older date returns `400` naming the earliest date we can serve, rather than quietly returning a partial set. ## Pricing 1 credit per call regardless of the count. ## FAQ ### What's the difference between this and `sold-by-zip`? This returns one integer (1 credit). `sold-by-zip` returns the full list (1 credit per 20 properties). Use this for cost-efficient screening; use `sold-by-zip` when you need details.

get_sold_count_by_zip

## What it returns Every residential property sold in a given US ZIP code within the last 365 days, with sale date, sale price, coordinates, and basic property characteristics (bed/bath, square footage, year built, lot size). Sourced from the `residential_sold` collection — a deduplicated rollup of MLS sold records refreshed on demand when the per-ZIP cache is older than 4 hours. ## When to use it - Build a "recent sales in my neighborhood" widget on a property page. - Estimate market velocity for a ZIP code (sales per month, median DOM). - Seed a comps analysis without specifying individual subject properties. - Sanity-check listing prices against actual sale prices. ## Date range By default the endpoint returns the full trailing 365 days. Pass `start_date`, `end_date`, or both (`YYYY-MM-DD`) to narrow that to a specific window — for example one calendar month at a time instead of re-pulling the whole year on every poll: ``` ?zip=95630&start_date=2026-08-01&end_date=2026-08-31 ``` Both bounds are optional and inclusive, and both are independent: pass only `start_date` for an open-ended window, or only `end_date` to cut off recent sales. Passing neither leaves existing behaviour unchanged. Either bound must fall within the last 365 days. An older date returns `400` naming the earliest date we can serve, rather than quietly returning a partial set. ## Pricing **1 credit per 20 properties returned**, rounded up. A request that returns 100 properties costs 5 credits. Use the `limit` parameter to cap the cost — a `limit=20` always costs exactly 1 credit. Charged only on `200`; `402`/`400`/`5xx` cost nothing. ## Errors | Status | Meaning | |---|---| | 400 | Missing `zip` parameter, non-integer `limit`, or a malformed / out-of-window `start_date` or `end_date`. | | 401 | Authentication failed or account missing. | | 402 | No subscription, or insufficient credits for the property count this ZIP would return. The error body includes the credit estimate so you can lower `limit` and retry. | | 503 | Upstream datastore or refresh error. Safe to retry. | ## FAQ ### How fresh is the data? The per-ZIP cache refreshes when stale (older than 4 hours) on demand. A first request to a cold ZIP may take longer while the refresh runs; subsequent requests within the 4-hour window hit cache. ### Why do some properties have `sold_price: null`? The MLS suppresses price on private sales, off-market transfers, and some agent-sale records. The property still appears (it sold), but the price field is `null`. Filter on your side if you need price-bearing records only. ### What counts as "residential"? Single-family, condo, townhouse, and multi-family (2-4 unit) records. Commercial, land-only, and 5+ unit multi-family are excluded at the collection level — they live in different collections not exposed by this endpoint. ### Why is `dom` sometimes `null`? Days-on-market requires listing-history dates that older records may not carry. For records that lack `dom` natively, we compute it best-effort from `list_date` to `sold_date`; when neither path resolves, the field is `null`.

get_sold_properties_by_zip

## What it returns Per-floor square-footage distribution for a US residential property, derived from a multi-stage AI analysis (photo/room detection, architectural-style inference, and multi-method validation). Returns the total square footage and a `square_feet_by_floor` map keyed by floor. ## When to use it - Break out living area by floor for renovation, valuation, or listing copy. - Sanity-check a single total-sqft figure against a per-floor split. **Note:** this is a heavy AI workflow — use a **45-second client timeout**. **Costs 1 credit per call.**

get_sqft_per_floor

Identical response shape to `info` — see that endpoint's docs for fields and FAQ. The difference: `info` is the fast lookup and may serve recently stored data; `updated-info` always returns the freshest available record. Use this when freshness matters more than the ~2-second latency cost — pricing decisions, just-listed alerts, post-sale confirmation. **Costs 1 credit per call** (cheaper than `info` because the cache hit-rate doesn't apply).

get_updated_property_info

Scan a US property address for location-based red flags — flood, crime, environmental hazards, school-district decline, and other neighborhood risks. Consumes the streaming risk pipeline to completion and returns the final aggregated report. Costs 5 credits per fresh request; repeat lookups of the same address within the cache window are free.

location_red_flags

## 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. |

preview_property_search

## What it returns An overall property-condition rating and confidence score, combining a database lookup with AI vision analysis of property photos you supply. Providing images yields a more accurate assessment than the address-only `property-condition` endpoint. ## Performance **Image analysis is slow — use a 60-second client timeout and cache responses.** ## Input modes - **Address only** — database lookup (same as `property-condition`). - **Image URLs** — pass `image_urls`, comma-separated (up to 25). - **File upload** — `POST multipart/form-data` with an `images` field (up to 15 files). - **Combined** — address + images for the most accurate result. **Costs 3 credits per call.**

property_condition_custom_photos

## What it returns The full set of properties matching your investment filters — each with valuation, investment metrics, condition, and location detail. This is the **charged** database search. ## ⚠️ Cost — read before calling **1 credit per property returned.** A search that matches 1,200 properties costs **1,200 credits**. Charging is all-or-nothing: if the balance can't cover the whole set, nothing is charged and the call returns `402`. **Always call `preview_property_search` first**, show the user the count and cost, and get an explicit yes before calling this. Never run a broad or location-only search without confirming the cost. ## When to use it - After `preview_property_search` and explicit user confirmation of the credit cost. - To pull a curated, filtered list of investment properties for an area. ## Required filters Same as `preview_property_search`: a `location` (city/county/ZIP — NEVER a whole state: state-wide queries time out before returning), a `property_status`, and at least one investment filter (or `allow_location_only=true` to waive only the investment filter). Send the SAME filters you previewed so the cost matches. ## Pricing **1 credit per matching property**, charged all-or-nothing on success. `400`/`401`/`402` cost 0 credits.

run_property_search

## What it returns A list of **people associated** with a property address — historical residents, current and former owners, related family members. Each person carries a `person_id` you can pass to `skip-tracing/person-details` for a full dossier. ## When to use it - Build outreach lists beyond just the legal owner (e.g. family members of a deceased owner). - Discover hidden parties to a property (trust beneficiaries, relatives). ## Pricing 1 credit per call. ## FAQ ### What's the difference vs. `property-owner`? This returns the broader set (everyone linked to the address), at the cost of less identity detail per person. Use `property-owner` for the legal owner; `associated-people` for the wider net; `person-details` for the deep dive on a specific person.

skip_trace_associated_people

## What it returns Full skip-trace dossier for a single person — current and previous addresses, phone numbers (with type and connectivity status), email addresses (with verification status), relatives, and associates. The `person_id` input must come from a prior call to `skip-tracing/associated-people` — this endpoint does not accept free-form name lookup. ## When to use it - You have a `person_id` from `associated-people` and want full contact details before reaching out. - You're enriching a CRM record with verified phones/emails for a known person. - You need historical address data to verify identity or reconstruct timelines. ## Pricing **1 credit per call.** A first call for a given `person_id` hits the upstream provider; subsequent calls within the per-user history cache are free. Identical calls from other accounts hit a shared global cache but still cost 1 credit (the data has value; the speed is the gift). ## Errors | Status | Meaning | |---|---| | 400 | Missing `person_id` field, or `person_id` not recognized by the provider. | | 401 | Authentication failed. | | 402 | Insufficient credits. | | 502 | Upstream skip-tracing microservice unavailable. Safe to retry with exponential backoff. | ## FAQ ### How fresh is the data? The upstream provider refreshes records on its own cadence; we don't control it. For privacy-sensitive use cases, treat addresses older than 12 months as stale. ### What's the difference between this and `skip-tracing/associated-people`? `associated-people` returns a list of people tied to a property address with minimal detail per person (name, relationship inference, `person_id`). This endpoint takes one of those `person_id`s and returns the full dossier for that one person. Use them together: list → drill down. ### Why might `current_addresses` be empty? The provider has no current-address record for the person. This is common for transient or recently deceased individuals. ### Is the data court-admissible? No. Skip-trace data is research-grade aggregation of public records and is not certified for legal proceedings.

skip_trace_person_details

## What it returns The **legal owner** of a US residential property given its address — name, mailing address (if different from the property), and contact methods (email and phone with connectivity/verification flags). Built from county records + skip-trace providers. ## When to use it - Direct-mail and cold-outreach campaigns for real-estate investors. - Owner verification before drafting an offer. - CRM enrichment by property address. ## Pricing 4 credits per address resolved. ## FAQ ### How fresh is the data? Upstream providers refresh on their own cadence. Treat data older than 12 months as stale for high-stakes outreach. ### Does this work for commercial properties? Limited. Residential is the primary use case. ### What's the difference between this and `associated-people`? This returns the *legal owner* (one or two persons). `associated-people` returns everyone the address can be linked to (residents, relatives, prior owners).

skip_trace_property_owner