---
title: "Bulk Property Search with ROI Fields — Lookup API"
description: "Paginated search across US residential properties, filtered by geo, price, beds, baths, sqft, year built, and days on market, with ROI fields returned."
---

# Paginated, filterable property search with ROI fields

`GET /api/properties/bulk-info/`

1 credit per property

## What it returns

Paginated search across all US residential properties matching geo + price + bed/bath/sqft/year-built/DOM/lot filters. Each result row carries ROI-relevant fields (AVM bands, financing/holding/project-cost breakdowns, potential ROI) — designed to feed investor screening dashboards, not detail pages.

## When to use it

- Build investor screening with multi-criteria filters (e.g. "active listings under $300k in zip 65802 with potential_roi > 0.15").
- Generate market reports: average AVM, average days on market, count of matches.
- Seed a recommendation engine with filtered candidate pools.

## Performance

**This is a slow endpoint — use a 60-second client timeout and cache responses.**

## Pricing

**1 credit per property in the response.** A page with 50 properties costs 50 credits. Use `page_size` to cap cost — for screening UI, smaller pages with manual paginate-on-demand is the cost-effective pattern.

## Errors

| Status | Meaning |
|---|---|
| 400 | Invalid filter values (e.g. `min_price > max_price`, non-numeric `beds_max`). |
| 401 | Authentication failed. |
| 402 | No subscription or insufficient credits for the page size requested. |
| 503 / 504 | Backend datastore unavailable or query timed out. |

## FAQ

### What's the difference between `property_status: "Active"` and `"Sold"`?
`Active` queries `residential_for_sale`. `Sold` queries `residential_sold` (same backing as the dedicated `sold-by-zip` endpoint). Both share the same response shape.

### Why is `dom` calculated rather than stored?
The MLS doesn't always carry days-on-market natively. When the field is absent, the endpoint computes it from `list_date` to `sold_date` (or to "now" for active listings).

### Can I filter by neighborhood?
Not directly. Filter by city + state + zip; the response includes a `neighborhood` field for client-side post-filtering.

### Is `avm_confidence` a percentage?
A `0.0`–`1.0` float. Higher = the AVM model is more confident in the band. Filter on `avm_confidence > 0.7` for high-quality estimates only.