Skip to main content
POST
Search companies

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Idempotency-Key
string
required

Unique operation key. Reuse only for identical retries, including across HTTP/MCP. Each new page needs a new key.

Body

application/json
query
string
required
Required string length: 1 - 500
filters
object

Lists use OR within a field, AND between fields; exclusions win. Each list permits at most 100 values. IDs must be positive integers. Domains are hostnames, not URLs; case, surrounding whitespace and trailing dots normalize. Empty lists do not restrict. Only current evidenced domain relationships match.

limit
integer
default:10

Maximum page size is subscription-owned: builder 25, professional 50.

Required range: x >= 1
target
integer

Requested accepted shortlist size, at least limit. When omitted, acquisition aims for one page and the stored-data shortlist remains capped at 100. An explicit target bounds the accepted list and acquisition goal; candidate scanning considers up to max(100, 2 * target) companies before relevance filtering. It is not a promise of that many matches. Keep target, including its omission, unchanged on continuation.

Required range: 1 <= x <= 1000
cursor
string | null

Opaque account-bound cursor referencing a server-owned shortlist. Keep query, filters, limit and target unchanged; use a new request key for each page.

background
boolean
default:false

Queue the same company operation through Active Job; poll GET /api/usages/{id}. This option does not change idempotent request identity.

Response

Completed company page (may be empty).

usage
object
required
request_allowance
object
required
coverage_status
string
required
Allowed value: "partial"
retrieval
enum<string>
required
Available options:
lexical,
hybrid
as_of
string<date-time>
required
next_cursor
string | null
required
withheld_units
integer
required
Required range: x >= 0
delivery_unit
enum<string>
required
Available options:
company,
observation
companies
object[]
required
ranking
string
required
Allowed value: "query_relevance_baseline"
candidate_limit
integer
required

Candidate scan cap before relevance filtering: max(100, 2 * target), or 100 when target is omitted. The accepted list is capped separately by target. Not a total-market count.

Required range: 100 <= x <= 2000
coverage
object
required