Home / Docs / API reference / Site filters

Site filters

count_sites and search_sites share one filter definition, so a count always matches the list it prices. Pass technologies, category or both; the other fields narrow the result.

Filter fields

FieldType and limitsNotes
technologieslist of up to 20 slugs, each 1 to 100 charactersSlugs from find_technologies, such as ["shopify","klaviyo"].
match"all" or "any", default "all""all" needs every listed technology on the site, "any" needs at least one.
exclude_technologieslist of up to 20 slugsDrops sites that use any of these. A slug can't be both required and excluded.
categorystring, 1 to 100 charactersA technology category such as "Marketing automation", case-insensitive. A site matches if it uses any technology in it.
versionstring, 1 to 50 charactersA version prefix for the matched technologies: "6.8" matches 6.8.1 but not 60.1.
rank_bucketslist of up to 20 positive integers or "unknown"Chrome UX Report popularity buckets as count_sites returns them: 1000 is the top 1k, 5000 is 1k to 5k, 500000 is 100k to 500k.
max_rankpositive integerOnly sites in the top N, such as 100000 for the top 100k. Sites with an unknown rank are dropped.
tldlist of up to 50, each 1 to 30 charactersTop-level domains such as ["com","co.uk"]. A leading dot is ignored.
cwvobject with lcp, inp and cls, each "pass" or "fail"Core Web Vitals at the 75th percentile. Pass means at or under Google's good threshold (LCP 2,500 ms, INP 200 ms, CLS 0.1). Sites without field data match neither. REST: cwv=lcp:fail,inp:pass.
device"mobile", "desktop" or "any", default "any"With mobile or desktop, the technologies must be detected on that device and CWV uses that device's field data. With any, either device counts and CWV uses mobile.

An unknown slug or category is an invalid_input error that names it, and for slugs lists them in unknown_technologies, so an agent can look them up and retry.

Example

Shopify stores in the top 100,000 that fail Largest Contentful Paint on mobile. On REST, list fields are comma-separated and cwv pairs each metric with its result:

curl "https://api.whichsitesuse.com/v1/counts?technologies=shopify&max_rank=100000&cwv=lcp:fail"

The same filter as MCP arguments:

{
  "technologies": ["shopify"],
  "max_rank": 100000,
  "cwv": { "lcp": "fail" }
}

An unknown slug is an invalid_input error that names it, like Unknown technology slug: hubspott. Call find_technologies to look up the right slug. The errors page shows the full body.