Skip to main content
POST
Count companies a search would match
Send what Company Search takes (filters, sql or es_query) and get back how many companies it matches, rounded, without any records. A count costs no credits, so you can size a list and work out what it would cost (one credit per record returned) before you search.

Reading the Total

total is rounded, and total_status (also the Total-Count-Status response header) says how to read it: A count is rounded, so adding or removing one record almost never changes it. For an exact total, run the search itself: its total is exact for selective queries. A count describes a list, not one record: it refuses (400, free) filters on fields that identify a single company: legion_id, its name, domain, LinkedIn URL and ticker. Whether a field is filled is fine, for example “public companies with a ticker”: "tickers.symbol": {"exists": true}; only a specific value is refused. To look one up, use Company Enrichment. Sent as filters, the response also carries generated_query, the query object the filters compiled to.

Limits

  • Free: no credits are used.
  • Works with zero credits left: a count needs an active plan that includes search (a trial counts too), not a balance, so you can size a list before you buy more. An expired plan answers 402; a plan without search, 403.
  • 10 counts a minute and 100 an hour per account (5 and 30 on a free trial), for each of person and company. Higher limits are available on request.
  • The same field rules as search: a filter on a field outside your plan is refused, and opted-out records are never counted.
  • GET works too, with filters, sql or es_query as query parameters (filters and es_query as JSON text). Prefer POST.

Authorizations

API-Key
string
header
required

Body

application/json

Request model for a company search's count.

query
deprecated

Deprecated: send sql or es_query. A SQL SELECT statement when text, a query object when an object (or text starting with "{"); still accepted as before.

sql
string | null

A SQL SELECT statement (no LIMIT or OFFSET clause: use limit and offset).

es_query
Es Query · object | null

A query object in the Elasticsearch query DSL, naming the response's field paths (bool, term, terms, match, match_phrase, range, exists, prefix, wildcard, nested). A GET may send it as JSON text.

pretty_print
boolean
default:false

If true, pretty-print JSON response with indentation.

filters
Filters · object

The company record's own field names; every one given must hold.

Response

Success - the rounded count of matching companies

How many records a search would match, rounded.

total
integer
required

How many records the query matches, rounded: to the nearest 10 under 100, else to two significant figures. Read it with total_status.

total_status
enum<string>
required

about: total is the rounded count. at_least: counting ran out of time, so total is a lower bound. under: fewer than total (10) match, possibly none.

Available options:
about,
at_least,
under
generated_query
Generated Query · object | null

Present when the search was sent as filters: the query object they compiled to, which es_query takes as is.