---
title: "Comp pack (paid, priced per pack) — with a FREE preview"
method: GET
path: "/api/v1/parcels/{id}/comp-pack"
tags: ["Parcels"]
---

# Comp pack (paid, priced per pack) — with a FREE preview

`GET /api/v1/parcels/{id}/comp-pack`

## Request

- Base URL: `https://propraven.com`
- URL: `https://propraven.com/api/v1/parcels/{id}/comp-pack`
- Auth: one of:
  - HTTP bearer
  - none

The Machine Storefront's comp pack: a subject valuation INDICATED BY comparable sales, wrapped with the comps that prove it. Answers the underwriting question "what is this worth, and which sales prove it?".

The comps are the SAME precomputed comparable_sales the free GET /api/v1/parcels/{id}/comps route serves, with the same read-time `similarity_score` (0–100) and `similarity_components` on every comp, plus `similarity_basis`, `similarity_method` and `comp_set_quality`; the subject's valuation fields come from parcels_serving. The indicated value is derived transparently (median comp $/sqft x subject sqft when both are known, else the median comp sale price) with an interquartile range, and is reconstructable from the comps in the same payload -- never a black-box AVM.

PRICE: per pack = clamp($2 x V(subject value) x Q(comp support), $1, $20). Q ramps on the comp count only: the similarity score is served but never priced (decoupled 2026-10-10, prices unchanged). A subject with ZERO precomputed comps has no evidence to support a number and is returned free, never charged. The exact price is advertised in the 402's accepts[0].maxAmountRequired (USDC atomic units, 6 decimals).

FREE PREVIEW: add preview=true for the subject summary, the comp count + median similarity, the exact price, and up to three MASKED comps (parcel/APN withheld, sale price rounded, date to the year). The precise indicated value and the unmasked comps are the paid product.

PAID ACCESS (preview omitted) requires ONE of: (a) x402 pay-per-call via a base64 signed x402 PaymentPayload in the `X-PAYMENT` header (receipt in `X-PAYMENT-RESPONSE`); (b) a genuine PAID PropRaven subscription entitlement; (c) anything else -> HTTP 402 whose `accepts` carries the exact requirements.

## Path parameters

- `id` string, required

## Query parameters

- `n` integer
- `radius` number
- `preview` boolean

## Headers

- `X-PAYMENT` string

## Response `200`

The comp pack (paid or entitled), or — with preview=true — the free masked preview, or a free $0 result when the subject has no comps.

- union
  - object
    - `subject` object, required
      - `canonical_id` string, required
      - `parcel_id` string, required
      - `state_fips` string, required
      - `county_fips` string, required
      - `total_assessed_value` integer, required
      - `market_value` number, required
      - `building_sqft` number, nullable, required
      - `property_type` string, required
      - `last_sale_price` number, nullable, required
      - `last_sale_date` string, required
    - `comp_count` integer, required
    - `radius_miles` number, nullable, required
    - `quote` object, required
      - `price` object, required
        - `amount` string, required
        - `currency` string, required
      - `price_usd` number, required
      - `price_atomic_usdc` string, required
      - `asset` string, required
      - `comp_count` integer, required
      - `breakdown` object, required
        - `base` number, required
        - `V` number, required
        - `Q` number, required
        - `price_raw` number, required
        - `capped` boolean, required
      - `pay` string[], required
      - `note` string, required
    - `preview` boolean, required
    - `sample` object[], required
      - `comp_parcel_id` string, nullable, required
      - `comp_apn` string, nullable, required
      - `comp_address` string, nullable, required
      - `comp_sale_price_approx` number, nullable, required
      - `comp_sale_year` integer, nullable, required
      - `comp_sqft` number, nullable, required
      - `comp_year_built` integer, nullable, required
      - `similarity_score` number, nullable, required: 0–100, computed at read time (see similarity_method on GET /parcels/{id}/comps). Not a pricing input.
      - `distance_miles` number, nullable, required
      - `rank` integer, nullable, required
    - `note` string, required
  - object: The delivered (paid / entitled / card) comp pack.
    - `subject` object, required
      - `canonical_id` string, required
      - `parcel_id` string, required
      - `state_fips` string, required
      - `county_fips` string, required
      - `total_assessed_value` integer, required
      - `market_value` number, required
      - `building_sqft` number, nullable, required
      - `property_type` string, required
      - `last_sale_price` number, nullable, required
      - `last_sale_date` string, required
    - `comp_count` integer, required
    - `radius_miles` number, nullable
    - `quote` object, required
      - `price` object, required
        - `amount` string, required
        - `currency` string, required
      - `price_usd` number, required
      - `price_atomic_usdc` string, required
      - `asset` string, required
      - `comp_count` integer, required
      - `breakdown` object, required
        - `base` number, required
        - `V` number, required
        - `Q` number, required
        - `price_raw` number, required
        - `capped` boolean, required
      - `pay` string[], required
      - `note` string, required
    - `paid_via` 'x402' | 'credits' | 'subscription' | 'card', required
    - `valuation` object, nullable, required: The comps-indicated value, its interquartile range, method and basis (comp_count, median_similarity 0–100, median_comp_price, median_price_per_sqft, subject_sqft).
    - `comps` object[], required
      - `comp_parcel_id` string, nullable, required
      - `comp_apn` string, nullable, required
      - `comp_address` string, nullable, required
      - `comp_sale_price` number, nullable, required
      - `comp_sale_date` string, nullable, required
      - `comp_sqft` number, nullable, required
      - `comp_year_built` integer, nullable, required
      - `comp_beds` number, nullable, required
      - `comp_baths` number, nullable, required
      - `similarity_score` number, nullable, required: 0–100, computed at read time exactly as GET /parcels/{id}/comps computes it (similarity_method); null only when no component can be computed. Never a pricing input.
      - `similarity_components` object, required: Each similarity component, 0–1.
        - `size` number, nullable
        - `year_built` number, nullable
        - `distance` number, nullable
      - `distance_miles` number, nullable, required
      - `rank` integer, nullable, required
      - `sale_price_reconciled` boolean, nullable, required
      - `comp_address_raw` string: The stored address casing, when the served upper-case `comp_address` differs.
    - `similarity_basis` string, nullable
    - `similarity_method` string, nullable
    - `comp_set_quality` object, nullable: The free comps' size label (#558): `size_mismatch` when more than half of the comps with a size are over 3x larger or smaller than the subject. A label: the comps are still listed.

## Other responses

- `400`: A query or body parameter is invalid. Nothing was read or charged.
- `401`: A present-but-invalid API key.
- `402`: Payment required. accepts[0].maxAmountRequired carries this pack's exact price (subject value x comp count, floor $1, cap $20) in USDC atomic units. Pay per call via x402, hold a paid subscription, or re-call with preview=true.
- `404`: Unknown parcel.
- `405`: The endpoint exists but does not support this method. `Allow` lists the methods it does.
- `500`: Unexpected server error. The body never carries database or driver text.

---

[API](https://skmtc.dev/propraven/apis/propraven-api.md) · [All operations](https://skmtc.dev/propraven/apis/propraven-api/llms.txt) · [OpenAPI document](https://skmtc.dev/propraven/apis/propraven-api/revisions/37f8158c4eda?raw)