# GoodLeads — size a segment (counts and cross-tabs, no key, no connector)

For agents and tools sizing a market before anyone buys. Operational cheat sheet: https://app.goodleads.club/llms.txt

**Three doors, same records, same counts — use the one your client can:** (1) the MCP server `https://mcp.goodleads.club/mcp`, for clients that can attach one; (2) the plain URL below, for any agent that can fetch a web address — no connector, no key; (3) `https://app.goodleads.club/buy.html`, for a person. Can't attach an MCP (a ChatGPT chat window, for one — adding a connector there is a one-time switch a person makes in settings)? Use door 2; you lose nothing for counting and sizing.

## One URL

`GET https://app.goodleads.club/api/v1/counts` — the free count, with an optional cross-tab. Parameters: `states` (comma list; empty = every live state), `filters` (JSON array, the one filter contract below), `group_by` (up to two fields, comma list).

```
# The shape: any states, any filter leaves, up to two group_by fields
curl -G "https://app.goodleads.club/api/v1/counts" --data-urlencode "states=<ST,ST>" --data-urlencode 'filters=[{"field":"<field>","op":"eq","value":"<value>"}]' --data-urlencode "group_by=<field>,<field>"

# Recipes — swap in your own fields
#   flow over time      group_by=formation_month
#   what kind of place  group_by=<an industry field>,property_classification
#   how reachable       group_by=reachability_tier
#   where               group_by=state
```

The reply carries the totals (`matching`, `sellable`, `verified_one`, `verified_both`) and `groups.groups[]` — each group's `values`, the same four counts, and its `share` of the whole; the top 50 groups come back and the rest are rolled into `groups.other`, so rows always add up. `groups.exact` is false when a count was cut short: a state still being counted is in `groups.incomplete_states` (never a wider figure in its place) — wait a minute and ask once more; an older figure for the same question is named in `groups.approximate_states`. Groupable — classification: `industry_sector`, `industry_name`, `naics_2_digit` … `naics_6_digit`, `sic_2_digit` … `sic_4_digit`, `gmb_category` (the Google Business category), `mcc`; geography: `state`, `msa_name`, `county_fips`, `principal_city`, `principal_zip`, `neighborhood`, `time_zone`, `tract_income_band`; also `property_classification` (RESIDENTIAL / COMMERCIAL / …), `entity_type`, `reachability_tier`, `filed_by`, `formation_month`. Classification is built by our pipeline from the filing and improves with every run. Records not yet classified read **Unclassified**: counted with the groups so rows add up, listed after the classified groups (a "largest" list never leads with them), with the classified share in `groups.classification`. A cell equals the count you get by filtering on that cell's values. Same call as `POST /api/v1/leads/summary` with a `group_by` array; over MCP it is `browse_leads(summary=True, group_by=[...])`. Counts need no key; contact details stay masked.

## More ways a count misleads

- **Reading groups.** Use `groups.groups[]` (each group's `values`, counts, `share`) and skip the rest. Top 50 by size for one field; a two-field cross-tab returns every cell (up to 400), so the table reads whole; any tail is in `groups.other` — filter to see it. `Unclassified` (and `No parcel data`, for building type) are real groups, listed last; they can be large, which is why a count by industry or MCC is a floor. Group by `industry_sector` or `industry_name`, not a NAICS code, for readable names.
- **Fields that depend on an analysis stage** (`entity_archetype`, `ra_*`, `gtm_segment`, `property_*`) are blank where it has not run, so filtering on one can drop a whole state. Check `per_state`.