Facebook Pixel
APILeads Database

List Facet Values

List the known values for any filterable facet on the leads database, most common first, with counts and substring search for building filter dropdowns.

GET /leads/facet-values

The known values for one facet, most common first.

GET /leads/facets tells you which parameters exist. This tells you what each one accepts. Together they are enough to build a filter UI without hard-coding anything.

Values come from the same precomputed tally that produces the facets block on a search response — this simply makes it addressable directly, instead of requiring you to run a search (which means already knowing a servable filter) just to read the counts back.

Parameters

ParameterRequiredDefaultNotes
facetYes—Any profile facet. GET /leads/facets lists the valid names
country_codeFor city only—Scopes to one country. Omit for the global tally
qNo—Case-insensitive substring match on the value
limitNo25Maximum 500

Example

curl -u "$LEADS_USER:$LEADS_PASS" \
  "https://api.connectsafely.ai/leads/facet-values?facet=job_level&country_code=US"
{
  "facet": "job_level",
  "results": [
    { "value": "Director", "count": 88110 },
    { "value": "VP", "count": 41203 },
    { "value": "CXO", "count": 9044 }
  ],
  "count": 3,
  "total": 3,
  "scope": "cc:US",
  "builtAt": "2026-09-02T10:00:00Z"
}
FieldMeaning
facetEchoes what was answered
results{ value, count }, count descending, ties broken alphabetically
countEntries in this page
totalEntries matching before limit — use it to tell "all of them" from "there are more"
scopecc:XX when scoped to a country, otherwise global
builtAtWhen the tally was computed. Absent if none has been built

Scope

Without country_code you get the global tally. With it, that country's — the same scoping the search facets block uses, so the numbers agree.

# every job function in the dataset
?facet=job_function

# job functions in the US only
?facet=job_function&country_code=US

City is the one exception

city is tallied per country only. A worldwide city list is neither bounded nor useful for filtering, so there is no global scope to fall back to and country_code is required:

curl -u "$LEADS_USER:$LEADS_PASS" \
  "https://api.connectsafely.ai/leads/facet-values?facet=city&country_code=US&q=york&limit=10"
{
  "facet": "city",
  "results": [
    { "value": "new york city", "count": 812441 },
    { "value": "york", "count": 3902 }
  ],
  "count": 2, "total": 2, "scope": "cc:US"
}

Omitting country_code for city is a 400 rather than an empty list, which would read as "this country has no cities".

City values are also capped at the 1,000 most populous per country. Beyond that is a long tail of misspellings and hamlets from four importers, which would swamp both storage and the response.

Substring, not prefix

q=york matches both york and new york city. Values are stored as the importers wrote them — greater london, new york city — so a prefix match would make the obvious search term return nothing.

Notes

  • Values round-trip. Pass a returned value back to /leads/search?<facet>= verbatim and it will match.
  • An unknown facet is a 400 unknown_facet, never an empty list — a typo must not read as "this facet has no values".
  • An unknown country is an empty list, not a 404 and not null. The response shape is stable, so a dropdown never needs a special case.
  • Counts are precomputed, not live. They reflect the last tally, named by builtAt.

Investors are not covered

This endpoint serves profile facets. Investor counts are computed live and filter-aware by GET /leads/investors — call it with limit=1 and read the facets block. GET /leads/facets reports values: false on investor facets for exactly this reason.

Requires a built tally

This endpoint reads the precomputed rollup. Before one exists it returns an empty list with builtAt absent — a 200, not an error. GET /leads/health reports rollupRows: 0 in that state.

By contrast GET /leads/facets reads compiled definitions and always answers, so parameter names are discoverable even on a fresh deployment.

On this page