Skip to Content
CompanySpec
API referenceDiscovery

Count companies

POST
/companies/count

How many companies match a search, and how many of them would be newly charged. Optionally break the total down by up to 3 fields with group_by. Takes the same filters as /companies/search, plus min_score, so you can check a search before you pay for it. Free.

Counts stop at a cap: 10,000 for filter-only counts, and 1,000 when you use semantic_query (the most a search can return). total_capped: true means there are more than total; add filters to narrow it down.

Counts have their own rate limit: 30 per minute on every plan, and 500 per day on the Free plan.

Authorization

bearerAuth
headerAuthorizationBearer <token>

Your API key, sent as Authorization: Bearer <key>. Create keys in the dashboard.

Request Body

application/json
  1. body

Filters shared by search, count, similar, page search and job search. Different filters are combined with AND. Inside one list, values match if the company has any of them, unless the filter has an *_operator (then the default is and: the company must have all of them).

query?string

Match against company name and domain (contains).

Lengthlength <= 250
semantic_query?string

Describe the companies you want in plain language, including who they sell to.

Lengthlength <= 500
semantic_weight?number

How much to favour relevance to semantic_query (1) over company size and web traffic (0).

Range0 <= value <= 1
Default0.7
countries?array<string>

HQ countries (ISO 3166-1 alpha-2). Matches any.

states?array<string>

Values from /values/states. Matches any.

cities?array<string>

Values from /values/cities. Matches any.

regions?array<string>

Values from /values/regions. Matches any.

office_locations?array<string>

Any office, not just HQ. Values from /values/cities or country codes. Matches any.

type?array<>

Ownership type. Matches any. Values from /values/type.

employees?array<>

Employee ranges. Matches any. Values: 1-10, 11-50, 51-200, 201-500, 501-1K, 1K-5K, 5K-10K, over-10K.

revenue?array<>

Annual revenue ranges (USD). Matches any. Values: under-1m, 1m-10m, 10m-50m, 50m-100m, 100m-200m, 200m-1b, over-1b.

founded_year?

Year of the most recent round.

industries?array<string>

Values from /values/industries. Matches any.

naics_codes?array<>

2–6 digits. Shorter codes include all codes beneath them. Matches any.

sic_codes?array<>

Values from /values/sic_codes. Matches any.

keywords?array<string>

Keywords from the company profile. Combined with keywords_operator.

keywords_operator?Operator

How the values in the list combine. and (default): the company must have all of them. or: it must have at least one.

Default"and"
Value in"and""or"
customer_types?array<string>

Who they sell to: B2B, B2C, B2G. Combined with customer_types_operator.

customer_types_operator?Operator

How the values in the list combine. and (default): the company must have all of them. or: it must have at least one.

Default"and"
Value in"and""or"
customer_segments?array<string>

Kinds of customers, for example enterprise, smb, government. Values from /values/customer_segments. Combined with customer_segments_operator.

customer_segments_operator?Operator

How the values in the list combine. and (default): the company must have all of them. or: it must have at least one.

Default"and"
Value in"and""or"
compliance?array<string>

Claimed certifications, for example SOC 2, HIPAA. Values from /values/compliance. Combined with compliance_operator.

compliance_operator?Operator

How the values in the list combine. and (default): the company must have all of them. or: it must have at least one.

Default"and"
Value in"and""or"
technologies?array<string>

Technology slugs from /technologies. Combined with technologies_operator.

technologies_operator?Operator

How the values in the list combine. and (default): the company must have all of them. or: it must have at least one.

Default"and"
Value in"and""or"
technology_source?string

Where a technology must have been found: website, jobs or any (default).

Default"any"
Value in"website""jobs""any"
vendors?array<string>

Service providers named in the subprocessor list (slugs from /technologies). Combined with vendors_operator.

vendors_operator?Operator

How the values in the list combine. and (default): the company must have all of them. or: it must have at least one.

Default"and"
Value in"and""or"
page_types?array<>

The company must have all of these page types.

funding_rounds?array<>

Has raised any of these round types. Values from /values/funding_rounds.

funding_amount?

Year of the most recent round.

funding_year?

Year of the most recent round.

investors?array<string>

Backed by any of these investors (names or domains).

workforce_size?array<>

Headcount ranges per department, for example [{"department": "engineering", "min": 20}]. Departments from /values/workforce_departments, or overall. All conditions must match.

workforce_growth?

Headcount growth over a period (m6 = 6 months, y1 = 1 year, y2 = 2 years), optionally for one department, as a percentage range.

recent_hires?

Companies that recently hired people matching these conditions. New hires usually appear 1–3 weeks after their start date.

hiring?

Companies with matching open job postings.

news?

Companies with matching news events.

require?array<>

Only return companies that have these: linkedin (LinkedIn URL), twitter (Twitter/X URL), icp (ICP paragraph), pricing_page (pricing page summary), funding (funding data), revenue (revenue range), founded_year, hq_city, open_jobs (at least one open job posting).

exclude?

Remove companies that match any of these, for example {"domains": ["acme.com"], "employees": ["1-10"]}.

group_by?array<>

Break the counts down by these fields (up to 3).

Itemsitems <= 3
min_score?number

Only count matches with at least this match.score, as in search.

Range0 <= value <= 1

Response Body

Counts.

application/json
  1. response
total*integer

Companies matching. Counting stops at 10,000 for filter-only searches and at 1,000 with semantic_query.

total_capped*boolean

true when there are more matches than total shows. Add filters to narrow it down.

would_charge*integer

How many of the counted companies are not yet paid for this billing month.

groups?

Present when group_by is set. With semantic_query, groups cover the counted (top 1,000) matches.

Example Request
curl -X POST 'https://api.companyspec.com/v1/companies/count' \  -H 'Content-Type: application/json' \  -d '{  "semantic_query": "practice management software for independent dental practices",  "countries": [    "US"  ],  "min_score": 0.6,  "group_by": [    "employees"  ]}'
Example Response
{  "total": 84,  "total_capped": false,  "would_charge": 81,  "groups": {    "employees": {      "1-10": 21,      "11-50": 38,      "51-200": 19,      "201-500": 5,      "501-1K": 1    }  }}

Get news events GET

Company news events such as launches, expansions, executive hires and funding. Costs 1 lookup unless already paid for this billing month.

Search companies POST

Find companies with filters, a plain-language `semantic_query`, or both. **Order.** With `semantic_query`, results are sorted by `match.score` (relevance, blended with company size and web traffic by `semantic_weight`). Without it, larger companies with more web traffic come first. `query` and `semantic_query` can be used together: `query` narrows by name or domain, `semantic_query` ranks. **Cost.** 1 discovery per company returned that isn't already paid for this billing month, including companies on later pages. The `show_*` options cost nothing extra. Use `/companies/count` first; it's free.