Skip to main content
POST
List Cohort Deals

Authorizations

api_key
string
header
required

Body

application/json

Event window, shared filters, the two cohorts and the side to list

cohortA
object
required
side
enum<string>
required

Which side of the comparison to list. 'A' and 'B' are the deals each rate was computed from; 'overlap' is the deals that matched both cohorts and were left out of both; 'excluded' is the deals that matched but were not compared, each with excludedBecause (post-close conversations only, order unknown, reopened, or ambiguous exposure).

Available options:
A,
B,
overlap,
excluded
startDate
string<date-time> | null

Start date for event time range (ISO 8601 format). Defaults to 14 days ago if not provided; the response's dataWindow echoes what was used.

endDate
string<date-time> | null

End date for event time range. Defaults to the time of the request, so events stamped in the future (a lost deal's placeholder close date, for example) are left out; pass an explicit later endDate to include them. The response's dataWindow echoes what was used.

filters
object

Filters to INCLUDE events: event type/category, company, contact, sentiment, call purpose, outcome, deal amount, library entity oIds (offerings, personas, segments, tags, use cases, competitors, alternatives, buying triggers, core features, objections, proof points, references), motion types, customer scope, custom extractor answers, and CRM deal context (opportunityIds, opportunityStatuses, dealMotions, dealTypes, dealStages, pipelinePhases, crmPipelines, minStalledDays). Deal filters AND on the same linked deal; values within one filter are OR'd. Events default to the activity feed's types, which leave out knowledge collection pages (docs, release notes): name their event types in eventTypes to read them.

exclude
object

Filters to EXCLUDE events matching these criteria (same shape as the entity/outcome match filters)

excludeTags
string[]

Exclude events matching any library entity that carries these reporting tag oIds. Use list_tag_groups to resolve tag oIds. Multiple tags are OR'd.

cohortB
object

The comparison group. OMIT it to compare cohort A against every other deal in the window — the usual question ('do deals where X came up win more than deals where it didn't?').

dealFilters
object

Deal-level cuts applied to BOTH sides, like the shared filters are for events: account segment, account headcount band, stakeholder persona, buyer title. E.g. { companySizeBands: ['1000-4999', '5000+'] } compares the cohorts among enterprise deals only.

outcome
object

The outcome the two cohorts are compared on. win_rate (default): won / closed — the truest and the slowest. advanced_within_days: the deal reached a later pipeline phase (not closed-lost) within days of its first matching conversation. faster_than_stage_median: the deal left the CRM stage it was in at that conversation, for a stage other than closed-lost, in less time than this workspace's median for that stage. next_conversation_positive: the deal's next conversation after it had POSITIVE overall sentiment. Use a leading outcome when win_rate returns insufficient_evidence; say which outcome a figure is about whenever you quote it.

linkScope
enum<string>

Which conversations count as belonging to a deal. OMIT it to use the workspace's own default (set beside its CRM mappings), or the product default, outcome_attribution, when the workspace never chose; the response says which applied in linkScopeSource. Which event-to-deal links establish that a conversation belongs to a deal. outcome_attribution (default): the product's own rule, the one behind the win rates in Insights — attribution links, links the CRM or a person made, links by a participant's contact email, and company-domain links only on a deal with at least two of them. Figures at this scope are comparable with Insights; at the others they are not. Where an event reaches several deals at one account, each link is graded on how well the event fits that deal (its contacts, timing and motion), and only the deal(s) it belongs to count; a graded-out link is read only at account_associated. crm_linked: only links the CRM or a person made — 'CRM-linked deals with a matching conversation'. The firmest association and a much smaller, differently selected population; not an unbiased one. single_candidate: crm_linked plus an inferred link when the event reaches exactly one deal and belongs to it. account_associated: every link, graded or not — the before/after view of the grading. The response reports the comparison under all four (acrossLinkScopes), so you can see whether the direction holds.

Available options:
crm_linked,
single_candidate,
outcome_attribution,
account_associated
dealOutcome
enum<string>

Only deals that stand this way in the CRM today, e.g. 'lost' to read the losses behind a low win rate. Omit for all.

Available options:
won,
lost,
open
result
enum<string>

Only deals with this result on the compared outcome, e.g. 'failure' with outcome advanced_within_days for the deals that did not move.

Available options:
success,
failure,
not_observable
limit
integer
default:25
Required range: 1 <= x <= 100
cursor
string

nextCursor from the previous page.

Response

List Cohort Deals

_metadata
object
required
side
enum<string>
required
Available options:
A,
B,
overlap,
excluded
label
string
required
totals
object
required

The whole side before outcome and paging are applied. Equal to the same side's counts in compare_cohorts for the same input — if they differ, the input differed.

matchingDeals
integer
required

Deals on this side left after the dealOutcome and result filters, before paging. Equal to totalDeals when neither is given.

deals
object[]
required
nextCursor
string | null
required

Pass as cursor for the next page; null on the last one.

dataWindow
object
required

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

linkScope
enum<string>
required

Which event-to-deal links establish that a conversation belongs to a deal. outcome_attribution (default): the product's own rule, the one behind the win rates in Insights — attribution links, links the CRM or a person made, links by a participant's contact email, and company-domain links only on a deal with at least two of them. Figures at this scope are comparable with Insights; at the others they are not. Where an event reaches several deals at one account, each link is graded on how well the event fits that deal (its contacts, timing and motion), and only the deal(s) it belongs to count; a graded-out link is read only at account_associated. crm_linked: only links the CRM or a person made — 'CRM-linked deals with a matching conversation'. The firmest association and a much smaller, differently selected population; not an unbiased one. single_candidate: crm_linked plus an inferred link when the event reaches exactly one deal and belongs to it. account_associated: every link, graded or not — the before/after view of the grading. The response reports the comparison under all four (acrossLinkScopes), so you can see whether the direction holds.

Available options:
crm_linked,
single_candidate,
outcome_attribution,
account_associated
linkScopeSource
enum<string>
required

Where linkScope came from: request (the caller named it), workspace_default (the workspace's deal matching rule, set beside its CRM mappings) or product_default (outcome_attribution, when the workspace never chose). The Insights win rates use the workspace's rule, so only a comparison made under a request scope is expected to differ from them.

Available options:
request,
workspace_default,
product_default