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
| Field | Type and limits | Notes |
|---|---|---|
| technologies | list of up to 20 slugs, each 1 to 100 characters | Slugs 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_technologies | list of up to 20 slugs | Drops sites that use any of these. A slug can't be both required and excluded. |
| category | string, 1 to 100 characters | A technology category such as "Marketing automation", case-insensitive. A site matches if it uses any technology in it. |
| version | string, 1 to 50 characters | A version prefix for the matched technologies: "6.8" matches 6.8.1 but not 60.1. |
| rank_buckets | list 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_rank | positive integer | Only sites in the top N, such as 100000 for the top 100k. Sites with an unknown rank are dropped. |
| tld | list of up to 50, each 1 to 30 characters | Top-level domains such as ["com","co.uk"]. A leading dot is ignored. |
| cwv | object 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.