Skip to Content
API & MCPPOSTCount companies

Companies

Count companies

How many companies match a set of filters and literal guards — and, with `group_by` (≤3 keyword facets), how they split.

POST/v1/companies/count
MCP tool count_companiesscope companies:readNo record cost by default

Parameters

filtersobjectoptional
facet → value; see list_filters
exclude_filtersobjectoptional
same shape, negated
must_termsany[]optional
Literal guards on OUR PROFILE of the company (not its web pages — that is site_text). Each group must match; inside a group any term does. A group is [“term”, “synonym”] (searched in all profile fields) or {field, terms}. Fields: summary, offerings, activities, product_categories, target_customers, target_customers_grounded. There is NO name or domain field — look a company up by domain with get_companies. Terms are exact phrases, case-insensitive, no variants. Examples: [[“ISO 13485”]] · [[“injection moulding”, “injection molding”], {field:“target_customers”, terms:[“automotive”]}]. (up to 10 items)
exclude_termsstring[]optional
(up to 50 items)
excludeobject[]optional
(up to 10 items)
site_textobjectoptional

WORDS ON THE COMPANY’S OWN CRAWLED PAGES — exact vocabulary the profile may not restate (a certification, a machine brand, a product code, a technology). Membership, like a filter: applies to search, count, lookalikes, segments and exports.

  • all = every term somewhere on the company’s pages (different pages count), any = at least one, none = not one.
  • pages narrows to page kinds: home, about, services, pricing, references, team, management, careers, contact, locations, certifications, machinery, shipping, payment, imprint, privacy, terms. Default: every crawled page, legal pages included. HOW A TERM MATCHES:
  • Case is ignored, EXCEPT a word written in capitals of 2–5 characters (US, IT, IP, AI, ISO), which matches only in capitals — so US does not hit “contact us”; IPs counts as IP.
  • No language stemming. Instead, unquoted words of 6+ letters also match words that START with them (géppark → gépparkunk, gépparkja; Maschine → Maschinenpark); shorter words also match +s/+es (pump → pumps).
  • An unquoted term of several words needs every word, in any order and anywhere on the pages.
  • “double quotes” = exact phrase: the words in that order, no variants (only case and e-mail/email fold).
  • e-mail and email are the same word. Punctuation inside a word (li-ion, 9001:2015) keeps its tokens together.
  • A brand can also be a surname or a word (“Engel”): check the snippets in site_text_match on each hit. LIMITS:
  • A term on more than 10,000 companies’ pages is resolved inside the rarest term’s companies (paged out in full up to 200,000). If EVERY positive term is on more than 200,000 companies’ pages the set is a sample: search says so in warnings, count_companies returns approximate:true with a lower-bound total.
  • Fastest with a country filter; phrases ~0.1–0.4 s, a very common word (millions of companies) 3–4 s. RESULTS: hits carry site_text_match — by default only when k ≤ 25, as {term: ‘±40 chars (kind)’}; name it in fields (or [’*’]) for the full per-term {url, kind, snippet ±60 characters of readable text, page_id} or null when the company’s pages lack that any term — each term checked on its own page; read a whole page with get_page. With site_text and no match/concept, hits are ranked by how many of the company’s pages match. With a match/concept too and ≤10,000 companies left, EVERY matching company is scored exactly — the text decides membership, the meaning only ranks.
group_bystring[]optional
(up to 3 items)
group_sizeintegeroptional
(min 1, max 100)
exclude_listsstring[]optional
ids of your exclusion lists (get_lists) to apply to this call (up to 20 items)
exclude_domainsstring[]optional
extra domains/URLs/e-mails to keep out of this call’s results (up to 1000 items)
within_listsstring[]optional
ids of your lists (get_lists, any kind) to search INSIDE: only companies on at least one of them — e.g. narrow last week’s export or your CRM accounts (up to 10 items)
clientstringoptional
AGENCIES: which of your clients this call is for (e.g. ‘acme’). That client’s always-exclude lists apply on top of your organization-wide ones — never another client’s. Set once per client conversation.

What your agent reads

The tool description exactly as an MCP client receives it in tools/list — it doubles as the full behaviour of the endpoint.

How many companies match a set of filters and literal guards — and, with `group_by` (≤3 keyword facets), how they split. The segment-sizing tool: measure a segment before pulling it. Cheap and not metered. Semantic clauses (match/concept) are NOT used here: a count is membership only. The size of a semantic segment is what start_export reports as total_above_floor. With site_text, `approximate: true` means a term was on too many companies' pages (every positive term on more than 200,000) to count exactly — `total` is then a lower bound and `total_note` says why; add a rarer term. EXCLUSION: exclusion lists marked auto_exclude apply automatically — organization-wide ones to every call, a CLIENT's ones (agencies) only to calls made for that client (`client`, or an API key bound to it); add more per call with `exclude_lists` (ids from get_lists) or `exclude_domains` (up to 1000 domains, URLs or e-mail addresses). An excluded company never appears — not in results, counts, lookalikes or exports. `applied_exclusions` in the response lists what was applied. QUALITY: gambling and adult sites and non-organisations (parked or for-sale domains, empty sites, personal pages) are left out by default. Name the vertical or leaf facet yourself to override (e.g. filters={vertical:'gambling_betting'}).
POSTRun several searches and merge themPOSTFind similar companies (lookalikes)