Two ways to say which records, one contract underneath:
  * a saved list — `list_id`, the 8-char id in `#browse?list=<id>`. Its states,
    filters, sort and inactive-or-holding toggle are read from the list;
    pass nothing else about the shape.
  * an inline shape — `filters` plus `state` (one state) or `states`
    (several); omit both for every live state (CO, CT, FL, NY, TX, VA).

`summary=True` returns the summary contract instead of rows — the same
numbers the buying surface shows, from the same code path: `matching`, `sellable`, `verified_one`, `verified_both`, `no_channel`, `unnamed`,
`facets`, `prices`, `quote` (present when `lane` or `cap` is given),
`exact`, `computed_at`, `quote_valid_until`, `per_state`. **Only `sellable`
— a matching record whose filing names a person — is ever billed or
delivered; never quote `matching` as a price.** name and address $0.25 per record · plus one verified phone or email $0.50 · plus both $0.70 (price rule v1; live prices always come from the summary call's `prices` block). Lanes: `all` / `best` / `contact`
(`all` = every sellable record at the name-and-address price; `best` =
each record at its own grade, verified first; `contact` = only records
with a verified phone or email). Cap: `{"type": "count|budget", "value"}`
— records for count, cents for budget. To buy, hand the same list / shape,
lane and cap to `create_checkout`.

Speak the canonical vocabulary — it is the same across every state:
`status` and `entity_type` take canonical values (`"active"`, `"LLC"`),
so `entity_type = "LLC"` matches Colorado's raw `DLLC`, Florida's `FLAL`,
and New York's spelled-out form alike; state-specific raw codes live
behind `status_raw` / `entity_type_raw` if you ever need them.
"Contacts" is the buyer's word for the records themselves — every record
names a person, so "contacts for new salons" needs no extra filter.
"Decision-makers" = filter
`contact_relevance_tier in ["Decision Maker", "Likely Decision Maker"]` —
our scored is-this-the-right-person opinion, available in EVERY state;
apply it when the buyer asks for decision-makers, never silently.
(`role_is_decision_maker: true` is the stricter, title-attested variant:
it means the state's own filing lists an authority title. Several states —
Colorado and New York among them — publish no officer titles at all, so
filtering on it there returns zero and silently drops real decision-makers.
Layer it on top only when you specifically want title-attested records.)
When a filter touches a (field, value) the requested state never populates
by design (e.g. `entity_type="SOLE_PROP"` in TX), the payload additionally
carries `zero_reasons` — machine-readable notes saying WHY the count is
zero and the nearest alternative; the key is absent otherwise. A
`formation_date` window that holds nothing explains itself the same way
on a summary: whether it ends before our earliest matching record, and
what the same filters match without the date limit.
Add `has_phone` / `has_email` for reachable ones. Worked example — active
LLC decision-makers with a phone, across all states, excluding two sectors:

    browse_leads(filters=[
        {"field": "status", "op": "eq", "value": "active"},
        {"field": "entity_type", "op": "eq", "value": "LLC"},
        {"field": "contact_relevance_tier", "op": "in",
         "value": ["Decision Maker", "Likely Decision Maker"]},
        {"field": "has_phone", "op": "eq", "value": true},
        {"field": "industry_sector", "op": "not_in",
         "value": ["Real Estate", "Finance"]},
    ])

`filing_kind` says what the state filing did. The default is Just started
(`formation`) — a business that did not exist before its filing — so a plain
call never returns an existing business that the state gave a new document
number. Widen with `include_existing=True` (every existing business with a
new filing at once) or by name: `filing_kind in ["registration", "conversion",
"name_change", "reinstatement", "address_change"]` returns existing businesses
the state published a fresh event about; `lead_class` on every row carries
the answer in the buyer's words — `Just started`, `New to <state>` (the
record's own state), `Established business, new entity`, `New trade name`,
`Back in business`, `Moved`. Never mix the two in one order — they are priced and
sold as separate lists. Closed businesses (`dissolution`) are excluded unless
named or `include_non_operating=True`. Every row also carries `last_event`
and `last_event_date` — the most recent thing the state published and the day
it published it.

Same owner: `cluster_size >= 2` is every business whose owner filed more
than one, so one call reaches the set; `cluster_code` is the record's place
in that group (`XF-O` / `XP-O` / `XM-O` an operating business, the `-V` codes
a holding company built around one). Blank on a single, so a filter on either
never matches a business with no related filing. `new_business_tier`
(`Confirmed new` … `Established`, newest first) is how sure we are the
business is genuinely new — filter on it, never sort by it; an empty result on
a fresh cohort means the score has not reached it yet.

Filter grammar (rendered from the schema — `list_filterable_fields(section="grammar")` is the full contract): a leaf is `{"field", "op", "value"}`; the top-level filters list is an implicit `and` group; group nodes `{"op": "and", "filters": [...]}` and `{"op": "or", "filters": [...]}` nest one or more children, `{"op": "not", "filters": [<one leaf or group>]}` negates exactly one. Operators by field type — text: eq, neq, in, not_in, contains, does_not_contain, exists, missing; number: eq, neq, gt, gte, lt, lte, between, in, not_in, exists, missing; date: eq, neq, gt, gte, lt, lte, between, in, not_in, exists, missing; boolean: eq, neq; geo: within. Narrower pseudo-fields — `run_manifest_id` eq; `cluster_ref` eq; `missing_stage` eq; `created_at` gt, gte, lt, lte, between; `geo_polygon` within; `geo_radius` within; `has_phone_or_email` eq; `filing_kind` eq, neq, in, not_in; `new_business_tier` eq, neq, in, not_in. `neq`, `not_in`, `does_not_contain`, `not` keep rows where the field has no value. `exists` / `missing` take no value; `in` / `not_in` take a non-empty list; `between` takes `[start, end]`, both required. A (field, op) pair outside its type's row is a 422 naming the row, never a 500. Records appear here the morning after the state posts them — speed is measured from publication, never from filing.

Args:
    state: Two-letter state code (e.g. `FL`, `CO`) for one state.
    states: Several state codes (rows or summary). Omit both `state` and
        `states` for every live state.
    list_id: A saved list id. Mutually exclusive with `state` / `states` /
        `filters` — the list already carries them.
    filters: Filter clauses in the grammar above (leaves and `and` / `or` /
        `not` groups). Use `list_filterable_fields` to discover the
        85 fields, each one's enforced operators and allowed values.
    page: 1-based page number.
    page_size: Rows per page (1–200 with a key; capped at 25 on the free
        tier, default 50).
    sort: `[{"field", "dir"}]`, one or more keys over any of the 76 sortable fields (`asc` / `desc`); a bare field name still works with `sort_dir`. Tier fields sort by rank (reachability_tier On Fire > Very Hot > Hot > Warm > Cold; contact_relevance_tier Decision Maker > Likely Decision Maker > Probable Contact > Uncertain Contact > Unlikely Decision Maker; contact_confidence_tier Verified Contact > Likely Contact > Possible Contact > Uncertain Contact; industry_confidence_tier confirmed > likely > possible > unknown; new_business_tier Confirmed new > Likely new > Uncertain > Likely established > Established); lead_ref ASC is always appended (total order). An unknown field or direction is a 422 listing the sortable fields — never a silent fallback. Default `reachability_score` descending.
    sort_dir: `asc` or `desc` (default `desc`) — used when `sort` is a bare field name.
    include_non_operating: Include inactive or holding businesses
        (default False — only the records we sell). A saved list's own
        toggle wins when `list_id` is given.
    include_existing: Include existing businesses with a new filing —
        opening a location here, formed in another state, back in
        business, a new entity, moved, a new trade name (default False —
        Just started only). Naming a `filing_kind` implies it.
    summary: Return the summary contract (counts, facets, prices, quote)
        instead of rows. Implied when `lane` or `cap` is given.
    lane: `all` / `best` / `contact` — asks the summary for a `quote`.
    cap: `{"type": "count|budget", "value": <int>}` — the dial the quote is
        solved against (records for count, cents for budget).

Returns:
    Rows: `{"items": [...], "total", "page", "page_size", "pages", "access_level",
    "_meta"}`. `_meta` is the provenance block every read carries:
    `schema_version` (the read-contract version — pin migrations to it),
    `freshness.data_refreshed_at` (when this state's data was last worked),
    `source` (public registry + derived-field attribution), `score_versions`,
    and `access_level` (preview = masked contacts, full = keyed). Keyless
    callers see `contact_name`, `email_primary`, `phone_primary` masked and may not filter the summary on them (422).
    Summary: the contract described above.