A comparative market analysis (CMA) estimates a property's value by comparing it against recently sold or currently listed properties that are similar in size, age, location, and type. Running a CMA only needs a handful of attributes per property — beds, baths, living area, lot size, last sale, and a valuation range — yet historically the only way to get them from the API was to pull a full property record and pay for every attribute, most of which a CMA never reads.

The comps dataset solves that. It is a lightweight projection of exactly the 24 attributes a CMA needs, billed at $0.02 per record — roughly 5× less than the $0.10 you pay for a full core record. This guide covers when to reach for comps, how to combine it with other datasets, how it's billed and accessed, the fields it returns, and how to use it to shape the comparable-property results returned by the Property Search endpoint.

The published API reference is canonical — see the BatchData developer portal for the full request and response schema. This guide is the how-to companion.

When to use comps vs. core or valuation

Pick the dataset that matches the job:

comps — Use when you are comparing properties: running a CMA, scoring a list of subject properties, or powering a comps grid. It returns the comparison-relevant attributes and nothing else, which makes it the cheapest way to get sale, size, and valuation signals at scale.
core — Use when you need the full property record: tax history, mortgage and lien detail, the complete ownership chain, full building characteristics, and every other attribute. A core record carries roughly 11× more attributes than comps and is priced accordingly at $0.10/record.
valuation — Use when you need the full valuation detail. Note that comps already includes the three headline valuation fields (estimatedValue, priceRangeMin, priceRangeMax), so for most CMA work you do not need to add valuation on top of comps.

A good rule of thumb: if you are comparing properties, start with comps, and only step up to core when you need an attribute comps doesn't carry.

Supported dataset combinations

comps is a projection designed to ride on top of a base dataset. The supported combinations are:

["basic", "comps"] — Recommended. The address and identity fields from basic plus the 24 comp-analysis attributes. This is the lowest-cost combination and the one the MCP comparables tools use by default.
["core", "comps"] — The full core record plus the comp-analysis projection, for when a single request genuinely needs both the complete record and the comp fields.
["basic", "comps", "valuation"] — Adds the full valuation dataset on top, when you need valuation detail beyond the three headline value fields.

Important: basic and core are mutually exclusive — a single request cannot include both. Choose basic for the lightweight combination or core for the full record, but never both in the same datasets array.

Access and pricing

How you access comps depends on your account's billing model:

Pay-as-you-go (no property data subscription): every dataset, including comps, is available under PAYG pricing. comps is billed at $0.02 per record — roughly 5× less than a full core record at $0.10.
Property data subscription: datasets are only accessible if you have purchased them. To use comps on a subscription, add the Comparable Properties add-on to your plan. The API does not fall back to PAYG pricing for datasets your subscription doesn't include.
On a subscription without the comps add-on: a request for ["basic", "comps"] or ["core", "comps"] will not error and will not be billed at the PAYG comps rate. Instead, the response returns the intersection of comps with whichever base dataset your token is provisioned for (basic or core) — the comps-only fields are simply omitted from the response.
MCP comparables tools follow the same rule. Because comparable_property_preview and comparable_property_page request comps by default, on a subscription without the comps add-on they return the reduced intersection field set rather than the full comps projection.

If you don't see the Comparable Properties option when provisioning an API token, your account is most likely on a property data subscription without the comps add-on.

Provision a dedicated token for comps

Billing is driven by how the API token used to make a request is configured — the per-record charge is determined by the datasets enabled on that token. A token with many datasets enabled can therefore bill at a higher rate than comparable analysis actually needs.

Because of this, the recommended practice for comp pulls is to provision a dedicated API token and enable only the datasets the workflow requires — typically just basic and comps (or core and comps when you also need the full record). A purpose-built comps token keeps each request billed at the comps rate and isolates this workflow from the broader tokens you use for fuller, more expensive record pulls.

When you create or edit the token in your API token settings, enable the Comparable Properties dataset alongside your base dataset and leave everything else off.

The 24 comps fields

The comps dataset returns the following 24 comp-analysis fields, grouped by category. The published spec on the developer portal is the canonical schema reference, and the internal data-dictionary sheet is the canonical source for the full field list; the table below is a quick reference.

#	Field	Type	Group
1	`building.bedroomCount`	integer	Building
2	`building.bathroomCount`	integer	Building
3	`building.livingAreaSquareFeet`	integer	Building
4	`building.totalBuildingAreaSquareFeet`	integer	Building
5	`building.yearBuilt`	integer	Building
6	`building.storyCount`	number	Building
7	`building.pool`	string	Building
8	`lot.lotSizeAcres`	number	Lot
9	`lot.lotSizeSquareFeet`	integer	Lot
10	`legal.subdivisionName`	string	Legal
11	`general.propertyTypeCategory`	string	Classification
12	`general.propertyTypeDetail`	string	Classification
13	`general.standardizedLandUseCode`	string	Classification
14	`general.vacant`	boolean	Classification
15	`owner.ownerStatusType`	string	Owner
16	`owner.ownerOccupied`	boolean	Owner
17	`sale.lastSale.price`	integer	Sale
18	`sale.lastSale.pricePerSquareFoot`	integer	Sale
19	`sale.lastSale.saleDate`	string (date)	Sale
20	`sale.flipLength`	integer	Sale
21	`listing.statusCategory`	string	Listing
22	`valuation.estimatedValue`	integer	Valuation
23	`valuation.priceRangeMin`	integer	Valuation
24	`valuation.priceRangeMax`	integer	Valuation

These fields map directly to the inputs a CMA relies on: building characteristics and lot size for like-for-like matching, classification and owner-occupancy for filtering, last-sale price and price-per-square-foot for the comparison itself, and the valuation range as a sanity check.

Note: alongside these 24 content fields, each record also returns the property _id identifier, so you will see 25 fields on the wire.

Running a comparable analysis with Property Search

The intended use of comps is to shape the comparable-property results returned by the Property Search endpoint (POST /api/v1/property/search). You supply a subject property via a compAddress object inside searchCriteria, and the API returns the properties most comparable to it — each one projected down to the 24 comps fields.

compAddress is a structured object (street / city / state / zip), not a free-text query string. The surrounding query scopes the geographic area the comparables are drawn from.

At its simplest, supply the subject property and request ["basic", "comps"]. The API applies sensible default matching rules:

{
  "searchCriteria": {
    "query": "San Antonio, TX",
    "compAddress": {
      "street": "10406 Burr Oak Dr",
      "city": "San Antonio",
      "state": "TX",
      "zip": "78230"
    }
  },
  "options": {
    "take": 10,
    "datasets": ["basic", "comps"]
  }
}

Tuning the comparable match

Each comparison dimension is controlled by a boolean use… toggle. When a toggle is on, a min/max pair bounds how far a comparable may differ from the subject property. For bedrooms, bathrooms, stories, and year built the bounds are deltas relative to the subject; for living area and lot size they are percentage deltas.

Option(s)	Default	What it controls
`useDistance`, `distanceMiles`	on, 1 mile	Restrict comparables to within a radius of the subject. Use the numeric `distanceMiles` (string distance values are deprecated).
`useBedrooms`, `minBedrooms`, `maxBedrooms`	on, −1 to +1	Match bedroom count within a delta of the subject (e.g. one fewer to one more).
`useYearBuilt`, `minYearBuilt`, `maxYearBuilt`	on, −10 to +10	Match year built within a span of years around the subject.
`useArea`, `minAreaPercent`, `maxAreaPercent`	off, −20% to +20%	Match living area within a percentage of the subject's square footage.
`useBathrooms`, `minBathrooms`, `maxBathrooms`	off, −1 to +1	Match bathroom count within a delta of the subject.
`useStories`, `minStories`, `maxStories`	off, −1 to +1	Match story count within a delta of the subject.
`useLotSize`, `minLotSizePercent`, `maxLotSizePercent`	off	Match lot size within a percentage of the subject's lot.
`useSubdivision`	off	Restrict comparables to the subject's subdivision / neighborhood.

A more selective request turns on additional dimensions and tightens the bounds:

{
  "searchCriteria": {
    "query": "San Antonio, TX",
    "compAddress": {
      "street": "10406 Burr Oak Dr",
      "city": "San Antonio",
      "state": "TX",
      "zip": "78230"
    }
  },
  "options": {
    "useDistance": true,
    "distanceMiles": 1,
    "useBedrooms": true,
    "minBedrooms": -1,
    "maxBedrooms": 1,
    "useYearBuilt": true,
    "minYearBuilt": -10,
    "maxYearBuilt": 10,
    "useArea": true,
    "minAreaPercent": -20,
    "maxAreaPercent": 20,
    "take": 25,
    "datasets": ["basic", "comps"]
  }
}

Aggregate metrics alongside the results

To get summary statistics across the matched comparables, add "aggComparablesMetrics": true to the same request. The response then includes an aggComparablesMetrics object (under results.meta.results) with averagePrice, averagePricePerSqft, and estimatedValue — computed across the comparables you matched, returned alongside the per-property rows you requested with take.

Using comps through the BatchData MCP server

The BatchData MCP server's comparables tools consume the comps dataset by default, so any MCP client (Claude Desktop, an IDE assistant, or your own integration) automatically gets the lower per-comp cost. The typical workflow is count → preview → page:

comparable_property_count — Returns the number of matching comparables plus the aggregate metrics (average price, average price per square foot, estimated value), so you can size the result set before pulling rows.
comparable_property_preview — Returns a focused 16-field preview projection of the top comparables, backed by the low-cost ["basic", "comps"] combination — ideal for a quick scan before committing to a full pull.
comparable_property_page — Pages through the full comparable set. It defaults to the low-cost basic + comps combination, making it roughly 5× cheaper than the same workflow against core.

Because these tools request comps by default, MCP-driven comparable workflows benefit from the cost reduction with no extra configuration.

A note on Property Lookup

comps is a valid dataset on the Property Lookup endpoint (POST /api/v1/property/lookup) as well, but Lookup retrieves records for addresses you already know — it does not calculate comparables. The comparable-matching options above apply only to Property Search. comps was designed to shape the comparable-property results of a Property Search, so that is where it delivers its value; reach for Property Lookup only when you already have the specific addresses you want and simply want their records.

Migrating from core

If you are currently requesting core purely to run comparable analysis, switch to comps:

Replace "datasets": ["core"] with "datasets": ["basic", "comps"] in your comparable searches.
Update any field references. The comp-analysis fields keep the same paths (e.g. sale.lastSale.price, valuation.estimatedValue), so most mappings carry over unchanged. If your code reads attributes outside the 24-field projection, keep core (or request ["core", "comps"] together).
Confirm your billing expectations — at $0.02/record, comp pulls cost roughly 5× less than the equivalent core pulls.