---
title: "Preview Search Results and Cost — Property Search API"
description: "Preview a property search before running it: returns how many properties match your filters and the exact credit cost of the full search. Free to call."
---

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