Skip to Content
API & MCPPOSTSegment companies

Companies

Segment companies

Split a set of companies into sub-segments you can write ONE message to.

POST/v1/companies/segment
MCP tool segment_companiesscope companies:readNo record cost by default

Parameters

searchobjectoptional
min_similaritynumberoptional
(min 0, max 1)
list_idstringoptional
domainsstring[]optional
(up to 2000 items)
method"auto" | "rules" | "semantic"optional
axesstring[]optional
(up to 12 items)
max_segmentsintegeroptional
(min 2, max 10)
min_sizeintegeroptional
(min 3, max 1000)
include_membersbooleanoptional

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.

Split a set of companies into sub-segments you can write ONE message to (a list is one filter, not one message: it mixes 3-person installers and 200-person manufacturers). Source: `search` (search_companies arguments; the exact list above min_similarity, up to 2,000), `list_id` (one of your lists), or `domains` (up to 2,000). method: 'rules' = split along the facet that separates the set best (industry, company type, size, customers…) — every segment comes with a `rule` you can pass as filters to search_companies / start_export to re-select it; 'semantic' = clusters by what the companies do, for splits no facet names (not reproducible as a filter); 'auto' (default) = rules when a facet splits cleanly, else semantic. Each segment lists what distinguishes it (facet values with their lift over the whole set) and its characteristic words — labels are derived from the data, never invented. `axes` restricts the facets considered (see list_filters). 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'}).