Preview search companies (free, limited fields)

The same search as POST /v1/companies/search (same body, same
filters, same errors), free of charge. Behind a workspace gate: a
workspace that is not in the rollout gets 404.

Each company has record_id (the domain) and saved. A company the
workspace saved (unlocked) comes back in full. Any other company keeps
only its identity and firmographic summary, and each of its signals
only signal_type, signal_subtype, signal_name, detected_at and
a short headline. Unlock a record with POST /v1/records/unlock.

view: total (default), net_new (not saved by this workspace) or
saved. include_total: true adds counts and total (the count of
the chosen view). A count that does not finish in time is null.

Limits: offset + limit <= 1,000; a daily number of previews per
workspace (429 preview_rate_limited); one preview at a time per
server (429 preview_busy, retry after 2 s). signals_per_entity is
at most 10. view net_new / saved does not work with content_filters.

Credit cost: 0.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

The preview search options (SIG-357), next to the search body.

signal_types
array of objects
required
length ≥ 1
signal_types*

Canonical signal type slug. Legacy SEC slugs (10k, 10q, 8k,
6k, 20f) and other registered aliases are also accepted and
are resolved server-side to the canonical value.

string
length ≤ 200

Filter by a single signal subtype. Prefer signal_subtypes (array); when both are sent they are unioned (the singular value acts as one more array member).

signal_subtypes
array of strings
length ≤ 25

Filter by signal subtypes — OR within the array (a signal matching ANY value passes). CROSS-TYPE: the list applies across ALL requested signal_types; SEC filing types share content-tag subtypes, so e.g. {"signal_types":["sec-8k","sec-10k"],"signal_subtypes":["aiInvestment"]} is a first-class pattern. Values are matched case-insensitively against the known vocabulary (see the per-type subtypes array on GET /v1/signals/types?include_counts=true); unknown values fall back to exact match (0 results — never a 400). NOTE: subtype filtering on high-volume types (linkedin-post-, work-milestones, website-intelligence, twitter-, seo-traffic) caps the scanned window to the most recent 14 days (a notice is returned).

signal_subtypes
date-time

ISO-8601 lower bound. Defaults to 50 days ago when omitted, so monthly-cadence signal types always have their latest batch in the default window (bounds the GROUP BY scan; pass an older value to query further back). NOTE: when the request includes an entity filter (industries, employee_count_min/max, revenue_min/max, or country), the scanned window is capped to the most recent 30 days; with a signal_subtype/signal_subtypes or content_filters filter as well, to the most recent 14 days. A signal_subtype/signal_subtypes filter together with a high-volume signal type (linkedin-post-, work-milestones, website-intelligence, twitter-, seo-traffic, hiring-trends, hiring-velocity) also caps it to the most recent 14 days. A wider detected_after is narrowed to a slice of that length ending at NOW (or, when detected_before is supplied, ending at detected_before), and the response notice states the window used. This is a temporary safeguard against statement timeouts; unfiltered (type-only) searches are not affected.

date-time
integer
1 to 100
Defaults to 20
integer
0 to 10000
Defaults to 0
integer
1 to 100
Defaults to 25

How many of each company's most-recent signals to attach.

string
length ≤ 24

Look up by stock ticker (staged rollout). A bare ticker is the US
listing (AAPL, BRK-B); a foreign listing has its exchange
suffix (T.TO, SAP.DE, 7203.T). Search then filters to that company's domain
(takes precedence over company_domains). match_basis is ticker.

string

Optional, with ticker: an exchange code or MIC (NYSE, XNYS,
TSX, XTSE, XETRA, ...) that stands for the ticker's suffix.
Unknown values return 400 unknown_exchange with the accepted list.

company_domains
array of strings
length ≤ 100

Filter to signals about these company domains (e.g., ["snowflake.com"]). Rolling out by workspace: where it is on, a blank value ("", spaces, "https://") returns a 400 invalid_filter_value that names the value (0 credits), and company_domain is added to this list. Where it is not on yet, a list of only blank values is ignored and the search runs without a domain filter.

company_domains
string
length ≤ 253

Singular alias for company_domains.

industries
array of strings
length ≤ 25

Filter by company industry.

industries
integer
≥ 0

Minimum company employee count.

integer
≥ 1

Maximum company employee count. Must be >= 1 — omit it for no upper bound (0 is rejected with a 400; it can never match).

string
length ≤ 100

Minimum annual-revenue bucket, inclusive (enrichment-backed). One of "Under 1 Million", "1 Million to 5 Million", "5 Million to 10 Million", "10 Million to 25 Million", "25 Million to 50 Million", "50 Million to 100 Million", "100 Million to 250 Million", "250 Million to 500 Million", "500 Million to 1 Billion", "1 Billion and Over". Matched case-insensitively; unknown labels return 400 with the valid list.

string
length ≤ 100

Maximum annual-revenue bucket, inclusive. Same bucket labels as revenue_min.

country
array of strings
length ≤ 250

Company HQ country (the response's hq_country). ISO-2 or ISO-3 codes (plus XK / XKX, e.g. "DE" or "DEU") or names, case-insensitive. Companies with no known HQ country never match (~72% of search companies have one). Unknown value: 400, 0 credits (did-you-mean for a misspelled name; a 2-letter value that is not a code, e.g. "ZZ", says so). More than 250 values: 400. Codes: GET /v1/filters (search_country). Rolling out by workspace: without search_country in /v1/filters, country is a 400 ("not supported on this endpoint").

country
company_country
array of strings
length ≤ 250

Alias for country (company HQ country). Both are unioned.

company_country
content_filters
object

FISH-892 — search inside the enriched content of social and podcast
signals. Think of it as: "give me the companies/people posting (or
talking) about X, and show me the posts." You get the deduped entity
with its matching signals attached.

Only supported for social + podcast signal types — the seven
social slugs: linkedin-post-company, linkedin-post-contact,
linkedin-comments-contact, twitter-company-posts,
twitter-contact-posts, youtube-company, youtube-contact — plus
the two podcast slugs: podcast-company, podcast-contact. If
content_filters is present and the request includes any other
signal_types, the API returns 400 invalid_request
(content_filters is only supported for social signal types); the
body lists both the allowed set and the offending types. (signal_types
itself is always required — a request without it is rejected at
validation, so there is no "typeless" content search.)

The five fields

Each field below is an independent contains / not_contains clause
(each capped at 20 terms, 1–500 chars per term — see
ContentFilterClause):

  • keywords — substring (ILIKE), case-insensitive, across the
    union of post/comment/video text and summaries (post_text,
    comment_text, video_description, summary, comment_summary);
    for podcast types, the transcript-derived text (headline,
    evidence, quotes[], talking_points[].{point,quote},
    offer_texts[], topics[]). The fuzzy catch-all.
  • tech_mentioned — exact (case-insensitive) match on the
    extracted technologies_mentioned[].name. Canonical names only:
    "Salesforce" matches, "Sales" does not.
  • competitors_mentioned — exact (case-insensitive) match on
    the extracted competitors_mentioned[].name. Canonical names only.
  • pain_points — substring (ILIKE) on the extracted
    pain_points[].topic.
  • initiatives — substring (ILIKE) on the extracted
    initiatives[].topic.

Podcast caveat: podcast payloads carry only transcript-derived
text — none of the four extracted arrays — so keywords is the only
clause that matches podcast content
; tech_mentioned,
competitors_mentioned, pain_points, and initiatives match social
types only and never match a podcast row. The same asymmetry governs
not_contains: pain_points.not_contains / initiatives.not_contains
exclude all podcast rows (the searched text is NULL for podcast,
and NOT (NULL ILIKE …) is not true — the same semantics as a social
row missing the field), while tech_mentioned.not_contains /
competitors_mentioned.not_contains keep podcast rows (an empty
array matches no excluded term).

Boolean logic

  • Within a contains array → terms are OR'd (match ANY).
  • not_contains → exclude the row if ANY term hits.
  • Across the five fields → clauses are AND'd (a row must
    satisfy every field you specify).

Prefer the structured fields over free text when they fit your intent:
"companies mentioning Salesforce" → tech_mentioned: {contains: ["Salesforce"]} (exact + fast), not keywords: {contains: ["Salesforce"]}.

Performance

Structured clauses (tech_mentioned, competitors_mentioned,
pain_points, initiatives) run against indexed extracted fields and
are typically sub-second. The one thing that gets slow is a broad
free-text keywords search over a wide date window — a common word
matches an enormous number of posts and grouping them is the cost. To
stay fast:

  • Keep keywords searches to a ≤ 30-day detected_after window.
    Social data refreshes on a biweekly (LinkedIn posts) /
    monthly (Twitter, YouTube, comments) cadence, so a 30-day window
    already contains everything fresh — scanning wider buys latency, not
    recency.
  • Pair keywords with a selective clause — a tech_mentioned /
    competitors_mentioned clause or company_domains shrinks the
    candidate set first and makes even a wide window fast.
  • Send fewer signal_types per call.

A broad query that still runs out of time returns 408 query_timeout
with tailored, ordered guidance (term names + fixes in
details.suggestions / details.broad_terms) — apply a suggestion and
retry; it is not charged. A 408 means "too broad," not "down." When the
SEARCH_REJECT_BROAD_KEYWORD flag is enabled (OFF by default), an
obviously-too-broad query is instead rejected up front with 422
query_too_broad
carrying the same guidance body. A 200 with 0
results
is normal for exact-match fields over sparse windows and
comes with an explanatory top-level hint.

boolean

true adds counts (total, net_new, saved) and total (the count of the chosen view).

signal_filters
array of objects
length ≤ 10

Filters on the data of each signal (for example funding amount, job
title, technology tags). The fields of each type and their operators:
GET /v1/signals/fields. A signal matches when it passes ALL filters;
an entity is returned when it has at least one matching signal of the
requested types in the window, and its signals are its matching
signals only. Every field must be a field of EVERY requested
signal_types (else 400 names the field and the types it works with);
a field with subtypes also needs signal_subtypes inside that list.
Cannot be combined with content_filters yet.

The scanned window is shorter than the default (each signal's data is
read): the response notice says so when it cut the requested
window. Rolling out by workspace: where it is off, a request with
signal_filters gets a 400 (signal_filters_not_enabled), 0 credits.
Same price per result as without filters.

signal_filters
string
enum
Defaults to total

total = every match; net_new = not saved by this workspace; saved = saved by this workspace.

Allowed:
Responses

404

The workspace is not in the rollout (the route does not exist for it).

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json