Skip to main content
GET
Every company your connectors can reach, hottest first by default, with how active it is right now (heat) and how well it matches your targeting (fit). This is the list the Accounts table draws: the same rows, filtered and ordered the same way. Search Companies answers a different question: it searches every company Clustr knows and can tell you a company exists, which says nothing about whether your workspace cares about it or can get into it. Companies on your excluded companies list never appear here. A row’s is_excluded is true only in the moments after you exclude its company, until the list catches up.

Heat and fit are two different questions

Heat is timing: is anything happening at this account? Fit is quality: is this the kind of account you want? Neither moves the other. A cold A+ is a good account nobody is talking to; a burning D is activity at an account outside your targeting. Rank on both, which is what the default order does: heat first, then fit, then the latest signal.

Heat

temperature is one of four bands. A signal is a LinkedIn engagement or a CRM activity (email, call, meeting, note) at the account. Path strength does not count: a strong path with no signal is cold. The band is worked out when you read it, so an account cools on its own as its last signal ages, without waiting for a refresh. The evidence ships with the band:
  • last_signal_at: the latest signal from either source.
  • last_signal_source: linkedin or crm.
  • last_signal_type: the engagement or CRM activity type of that signal, when known.
  • signals_30d: how many signals landed in the last 30 days, both sources.
  • has_open_deal: an open CRM deal is resolved to this account.
Signals are stored per account and refreshed in the background, at most about 15 minutes apart while the list is being read, so a brand-new engagement or CRM activity can take up to that long to warm an account.

The grade

fit_grade is A+ to D, and it is the fraction of your configured criteria this account meets, banded: The criteria are your target-account list, your tier vocabulary and each dimension of your Company ICP. The divisor is only the criteria you have configured, so a criterion you never set cannot drag an account down, and nothing earns an A+ for being the best of a bad list. An ICP dimension we hold no value for (no known headcount, say) is skipped for that account rather than counted as a miss. Its status in the breakdown is unknown.
No fit_grade is not a bad grade. It means the workspace has defined no ICP, no tiers and no target list, so there is nothing to grade against and no letter would be honest. D is the opposite: criteria exist and this account met none of them. Treat absent and D as different answers.
fit_score is not comparable across workspaces. It is a fraction of what that workspace configured, so 0.8 on a workspace with four criteria and 0.8 on one with one criterion are not the same claim. Compare grades within a workspace, never between.
fit_reasons ships with the grade and names what scored: the matched ICP’s title, then each criterion met (["Mid-market SaaS", "Target account", "Tier 1", "Industry"]). Nothing downstream has to reconstruct the reasoning. fit_breakdown goes further: every configured criterion, met or not, with the points it is worth and the points the account earned. fit_score is the earned points over the points available.

When a grade changes

A grade is refreshed by the change that affects it:
  • Change your targeting (a tier set on an account, an ICP edited, a tier added or reordered) and the affected grades are recomputed on that request. Set a tier with Set Account State.
  • New accounts your network reaches are graded at the next refresh of your accounts, along with anything whose targeting inputs moved with it. That is also when a change to the target list reaches the grade, because whether an account is a target is part of that refresh.
So a grade can trail a target-list import by one refresh. Everything else is immediate.

Which id to use

Each row carries clustr_account_id, the account’s Clustr ID. Use it wherever a route asks for an account, including Set An Account’s Tags and Set Account State. The row also keeps two earlier ids for integrations built before Clustr IDs, and they are not interchangeable: id is the company’s LinkedIn numeric id, and company_id is the id the tag and account state routes took. A row’s tags are the account’s tags, each carrying the group_id of the field it came from.

Competitor activity

With the Competitor Monitoring add-on, an account a watched competitor has touched carries competitor_activity: the same object the Accounts table’s Competitors columns read. It is absent when no competitor has engaged a counted person at the account, and on every row without the add-on. Filter on it with competitor (any, or competitor ids), competitor_pressure (hot, warming, active, cooling, dormant, none), competitor_last_touch (7d, 30d, 90d, older, never), competitor_side (defense, attack), competitor_active_days and competitor_pitch_days. Sort on it with sort=lastCompetitorActivity, lastCompetitorPitch, competitorPitches or pressure_path (competitor pressure times the best path’s strength); accounts no competitor touched sort last. Without the add-on, these filters and sorts answer 403.

Last CRM activity

The latest activity logged in your CRM against the account’s contacts:
  • last_crm_activity_type: its type (EMAIL, CALL, MEETING, …).
  • last_crm_activity_at: when it happened.
  • last_crm_activity_provider: the CRM it was logged in, hubspot or salesforce.
  • crm_activity_count: how many activities are logged in all.
All four are absent when the account has no CRM activity.

Smaller rows with include

Leave include out and every row is whole, as it has always been. When you only need the flat fields (name, domain, heat, fit grade, counts, the warmest connector), send include=none for the base row alone, or name the heavy parts you want back, comma-separated: A part you leave out is absent from the row, not null. An unknown value is a 400 that lists the allowed ones.

Paging

Pages are page_size rows (default 50, at most 200). has_more is true while another page exists; there is no total count.

Authorizations

Authorization
string
header
required

The API key you created on the API settings page of the Clustr app.

Headers

X-Clustr-Fresh
enum<string>

Send 1 for about 10 seconds after a write of your own: the read waits up to queries.clickhouse.write_wait_ms (default 6 s) for that write and is never answered from a last-good copy. Do not send it on every request.

Available options:
1

Query Parameters

company_ids
string[]

Keep only these accounts, by Clustr ID (acc_…). Repeat the parameter for several.

sort
string

heat (default): hottest first, then best fit, then latest signal. fit: best grade first. path: warmest entry path first. recency: latest LinkedIn or CRM signal first. With Competitor Monitoring: lastCompetitorActivity (latest competitor touch first), lastCompetitorPitch (latest pitch first), competitorPitches (most pitches in 30 days first) and pressure_path (competitor pressure times the best path's strength); accounts no competitor touched sort last. order flips any of them.

order
enum<string>
Available options:
asc,
desc
name
string

Contains-match on the account name only.

strength_band
string[]

Best path strength bands to keep, each written low-high on the 0 to 1 scale of best_strength: 0-0.25 (weak), 0.25-0.5 (fair), 0.5-0.75 (good) and 0.75-1 (strong). A band starts at its low value and runs up to its high value, and a band ending at 1 includes a perfect score. Repeat the parameter for several; an account in any band is kept.

page
integer

Which page to read, from 1, on a list numbered by page.

page_size
integer

Default 50, at most 200.

force_refresh
enum<string>

true bypasses the cache.

Available options:
true
cursor
string

The previous page's next_cursor: the next page, in place of page. It carries the row number the next page starts at. A cursor that does not decode is a 400. page/page_size keep working for customers that send no cursor.

tier
string[]

Narrow to accounts whose account_states.tier_id is one of these tier ids (uuid), or __none__ for no tier. Repeatable, or one comma-separated value; OR-within. Any other non-uuid value is a 400.

status
string[]

Deprecated: a tag filter. Former status ids (uuid) are translated through the status -> tag map into the account tags they became; the literal none means no account tag and composes with ids ("New or X"). Equivalent to tag / tag_group_empty. Repeatable, or one comma-separated value; OR-within. Anything else is a 400.

tag_group_empty
string[]

Narrow to accounts carrying NO tag in these tag fields (uuid ids). The "New" view sends the account tag field's id: no tag yet. ANDs with tag and every other filter. Repeatable, or one comma-separated value. Anything that is not a uuid is a 400.

industry
string[]

Case-insensitive exact match on the account's displayed industry. Repeatable, or one comma-separated value; OR-within. __none__ keeps the accounts with no industry.

icp
string[]

Narrow to accounts that are a STRONG match for one of these Company ICPs, by ICP id (uuid). Repeatable, or one comma-separated value; OR-within. A non-uuid value is a 400.

Not the same filter as icp_fit: that one asks whether the account is strong (or partial, or neither) for ANY of the tenant's ICPs, which is a superset. This one names the ICP, and is what the ICP · <title> view means. Both compose, and both are honoured by /v2/accounts/counts.

temperature
string

Narrow to accounts in one of these heat bands. A signal is a LinkedIn engagement or a CRM activity. burning (an open CRM deal, or a signal in the last 14 days and another within 30), warm (a signal in the last 30 days), cool (a signal in the last 90 days), cold (otherwise; path strength does not count). Repeatable, or one comma-separated value; OR-within. Unknown values match nothing.

owner
string[]

Account owner ids (directory.owners), OR'd; repeated keys or one comma list. Matches annotations.account_states.owner_id. unassigned matches accounts with no owner. A legacy email value resolves through the owner directory; a value that resolves to nobody narrows to nothing.

cs_owner
string[]

CS owner ids (directory.owners), OR'd; repeated keys or one comma list. Matches annotations.account_states.cs_owner_id. unassigned matches accounts with no CS owner.

Accounts whose displayed name or industry contains this text. Case- and accent-insensitive ("societe" finds "Société").

segment
enum<string>

One segment: in-crm (matched to a CRM company), open-deals (an open CRM deal), target (on the target list). Omitted, every account.

Available options:
in-crm,
open-deals,
target
segment_not
string

Segments to leave out, as a comma list: in-crm (not matched to a CRM company), open-deals (no open CRM deal), target (not on the target list). AND'd with segment.

employees
string[]

Company size buckets, as /v2/accounts/filter_options lists them (employees). Repeated keys; OR-within. Exact match. __none__ keeps the accounts with no value (OR'd with the rest).

revenue
string[]

Revenue buckets, as the filter options list them (revenues). Repeated keys; OR-within. Exact match. __none__ keeps the accounts with no value (OR'd with the rest).

country
string[]

HQ countries, as the filter options list them (countries). Repeated keys; OR-within. __none__ keeps the accounts with no HQ country.

abs
string[]

Account Research state: ready, ready_empty, running, failed, none. Repeated keys; OR-within.

connector_owner
string[]

Owner ids (directory.owners) whose connectors reach the account. Repeated keys; OR-within. A legacy email resolves through the owner directory; a value that resolves to nobody narrows to nothing.

connector
string[]

Connector LinkedIn ids, of which at least one must reach the account (the Connected to column). Repeatable, or one comma-separated value; OR-within.

activity_type
string[]

The account's most recent CRM activity type (activity_types in the filter options). Repeated keys; OR-within; case-insensitive. __none__ keeps the accounts with no CRM activity.

is_customer
boolean

true keeps the accounts on your client companies list, false the others. Any other value is a 400.

crm_activity_within_days
integer

Keeps the accounts with a CRM activity (an email, call, meeting, note or task at the company) in the last this many days. A positive whole number; anything else is a 400.

Required range: x >= 1
icp_fit
string[]

How well the account matches ANY of the tenant's ICPs: strong, partial, none. Repeated keys; OR-within. See icp for one named ICP.

fit
string[]

Account grades to keep, A+, A, B, C, D, and __none__ for no grade. Repeated keys; OR-within. Unknown values match nothing.

tag
string[]

Account tag ids (uuid). Several ids match an account carrying ANY of them. Repeatable, or one comma-separated value. A non-uuid value is a 400.

intro_tag
string[]

Tags on the account's WARM INTROS, path tag ids (uuid): keeps accounts with at least one warm intro carrying them. Several ids match an account with warm intros carrying ANY of them. Repeatable, or one comma-separated value. A non-uuid value is a 400.

competitor
string[]

any: accounts a watched competitor has touched. Competitor ids (uuid): accounts one of THESE competitors has touched, as the Competitors column shows them. any with ids is any. Repeatable, or one comma-separated value; OR-within. Any other value is a 400; without the Competitor Monitoring add-on, a 403.

competitor_side
string

defense (a competitor is at your customer or an account with an open deal) and/or attack (at a target or ICP account), OR'd; one comma-separated value. Anything else is a 400.

competitor_active_days
integer

A watched competitor touched someone at the account within this many days (1 to 3650).

Required range: 1 <= x <= 3650
competitor_pitch_days
integer

A watched competitor pitched someone at the account within this many days (1 to 3650).

Required range: 1 <= x <= 3650
has_notes
string

with_notes (the account carries a note) and/or without_notes, OR'd. Repeatable, or one comma-separated value. An unknown value matches nothing.

customer_of
string[]

Accounts that are a customer of a watched competitor (Confirmed or Likely, not rejected), as the Customer of column shows them: any, or competitor ids (uuid). Repeatable, or one comma-separated value; OR-within. Any other value is a 400; without the Competitor Monitoring add-on, a 403.

renewal
string

The Renewal date column: the date entered on the competitor customer, else the start of its estimated window. passed, 90d, 180d, 365d (within the next 3, 6 or 12 months) or later. Repeatable, or one comma-separated value; OR-within. Any other value is a 400; without the Competitor Monitoring add-on, a 403.

competitor_pitches
string

The Pitches column (watched competitors' pitches in the last 30 days), as count buckets: 3, 2-5, 51+. Repeatable, or one comma-separated value; OR-within. Without the Competitor Monitoring add-on, a 403.

competitor_people
string

The People column (people at the account watched competitors engaged), as count buckets: 3, 2-5, 51+. Repeatable, or one comma-separated value; OR-within. Without the Competitor Monitoring add-on, a 403.

strength_min
number

Minimum best path strength, 0 to 1.

Required range: 0 <= x <= 1
include_discarded
boolean

true also returns the accounts the workspace dismissed, which are hidden by default.

only_discarded
boolean

true returns only the dismissed accounts. Takes precedence over include_discarded.

contact_count
string

Buyers reached (contact_count), in buckets: N (exactly N), A-B (A to B inclusive) or N+ (N or more). The app sends 1, 2-5, 6-20, 21-50, 51+. Repeatable, or one comma-separated value; OR-within. Malformed values match nothing.

connector_count
string

How many connectors reach the account (connector_count), in the same bucket spelling as contact_count. The app sends 1, 2-5, 6-20, 21+. Repeatable, or one comma-separated value; OR-within.

last_signal
string

When the account's last LinkedIn or CRM signal was (last_signal_at): 7d, 30d, 90d (within that many days), older (more than 90 days ago), never (no signal). Repeatable, or one comma-separated value; OR-within. Unknown values match nothing.

added
string

When the account first appeared for the workspace (first_seen_at): 7d, 30d, 90d, older, never, as for last_signal. Repeatable, or one comma-separated value; OR-within.

deal_stage
string[]

Accounts with an OPEN CRM deal in one of these stages, by the stage label the row's deal_stage carries (deal_stages in the filter options). Case-insensitive. Repeated keys only, since a label may contain a comma; OR-within.

competitor_pressure
string

Accounts whose competitor pressure (the Pressure column) is one of hot, warming, active, cooling, dormant, or none (no competitor activity). Repeatable, or one comma-separated value; OR-within. Any other value is a 400; without the Competitor Monitoring add-on, a 403.

competitor_last_touch
string

Accounts by when a competitor last engaged someone there (the Last touch column): 7d, 30d, 90d (within that many days; the windows overlap), older (over 90 days), never (no competitor activity). Repeatable, or one comma-separated value; OR-within. Any other value is a 400; without the Competitor Monitoring add-on, a 403.

include
enum<string>[]

Optional. Leave it out for the full row, as before. Name the heavy parts you want back, comma-separated, or none for the base row alone.

  • top_connectors: the row's best connectors, each with photo, title, strength and the path through.
  • connectors: every connector connector_count counts, by id and name.
  • crm_activities: the account's recent CRM activities. crm_activity_count and the last activity's type and date stay on the base row.
  • fit_breakdown: every criterion behind fit_grade, met or not.
Available options:
none,
top_connectors,
connectors,
crm_activities,
fit_breakdown

Response

Typed result envelope. Each row also carries temperature (burning | warm | cool | cold), the heat band the temperature parameter filters on. The envelope carries updating: true while a settings change is being applied in the background: the rows are the previous numbers until it finishes. Omitted otherwise. It carries next_cursor whenever a further page exists: pass it back as cursor for the next page. Omitted on the last page.

success
boolean
required
data
object
required