Skip to main content
POST
Search Findings

Authorizations

api_key
string
header
required

Body

application/json

Findings search query and filters

query
string

What was said, in plain words: the content you want (e.g. 'worried the output is too much to act on', 'pricing objections'). The query picks the finding types and ranks results by how directly they answer it; it never filters events. Use eventFilters and startDate/endDate for that: for 'pricing objections from lost deals', query 'pricing objections' with eventFilters.opportunityStatuses ['LOST']. Required unless customExtractorOIds is provided.

Example:

"objections from prospects"

customExtractorOIds
string[]

Filter to findings produced by these workspace-defined custom extractors (oIds, as returned in each finding's customExtractor field). Exact filter — when provided, natural-language translation of the query is skipped and only these extractors' findings are returned.

findingOIds
string[]

Fetch these exact findings by oId (ex_*). Every named finding comes back whatever its date (no 14-day default; startDate/endDate still narrow if given), limit and offset do not apply, and ids with no row are listed in notFound. Cannot be combined with query, customExtractorOIds or insightOId; the other filters still narrow.

Required array length: 1 - 100 elements
Example:
orderBy
enum<string>

With query: 'relevance' (default) ranks findings by how directly they answer the query; 'recency' returns newest first. Other modes are always newest first.

Available options:
relevance,
recency
searchTerms
string[]

With query: the names and words a matching finding would contain (a competitor, product, account or phrase, with its spelling variants). Findings whose text, or whose account's name, contains one are ranked alongside the newest findings. Omit to have them derived from the query.

Maximum array length: 15
Required string length: 1 - 80
startDate
string<date-time> | null

Start date for event time range (ISO 8601 format). Defaults to 14 days ago if not provided.

Example:

"2026-08-01T00:00:00Z"

endDate
string<date-time> | null

End date for event time range (optional; if omitted, no upper bound is applied)

eventFilters
object

Additional filters to narrow down which events to search

speakerSide
enum<string>

Who said it: 'external' is the buyer's side, 'internal' the workspace's own people. Narrows a query to that side, or, given alone, returns every finding type from that side. The side is read per finding (its recorded speaker, a custom extractor's perspective, the participant it was attributed to), so it combines with customExtractorOIds. Findings nothing attributes to a speaker, and document findings, match neither side.

Available options:
internal,
external
Example:

"external"

attributedPersonaOIds
string[]

Filter to findings SPOKEN BY contacts classified into these personas (e.g. 'objections raised by CTOs'). Different from eventFilters.personas, which matches findings TAGGED with a persona. Attribution exists only for email and call findings with a resolved speaker.

insightOId
string

Scope results to one Insight: only findings from the events that Insight covers, resolved the same way the Insight's own run resolves them. Given alone, it also selects the finding types and custom extractors the Insight reads. Combined with query or customExtractorOIds, it narrows the events only and your own source selection is kept.

Example:

"rcfg_XVPcS3dLZFqzfQIfSeCpk"

limit
integer
default:100

Maximum results to return (default: 100, max: 200)

Required range: 1 <= x <= 200
Example:

100

offset
integer
default:0

Offset for pagination

Required range: x >= 0

Response

Matching findings with pagination info

_metadata
object
required
findings
object[]
required

Matching findings, each with its event/company/speaker linkage

total
number
required
hasMore
boolean
required
dataWindow
object
required

The time span these numbers cover. Compare numbers from two tools only when their dataWindow kind and dates match.

rankedBy
enum<string>

With query: how this page was ordered. 'relevance': the candidates (the best text matches for the search terms, in any conversation finding type, and the newest findings) were scored for how directly they answer the query. 'text_match': scoring was unavailable, so text matches lead, best match first. 'recency': asked for, past the ranked candidates, or nothing could be scored.

Available options:
relevance,
text_match,
recency
search
object

With a ranked query: the search terms used (derived from the query, or your searchTerms), how many findings matched them, and how many candidates were ranked. Empty terms mean the query names only a kind of finding, so the newest findings were ranked.

notFound
string[]

With findingOIds: the requested ids no finding came back for (unknown, deleted, in another workspace, or excluded by the other filters given).