Skip to main content
POST
Compare Cohorts

Authorizations

api_key
string
header
required

Body

application/json

Event window, shared filters and the two cohorts

cohortA
object
required
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
stratifyBy
object

Also make the comparison WITHIN each value of this dimension and pool the result. Use { by: 'segment' } (or a tag group, or deal_stage_at_event) whenever the cohorts could simply sit in different kinds of deal — it is what tells a real effect from a mix effect.

materialGapPoints
number
default:10

The gap, in PERCENTAGE POINTS, below which two rates count as alike — what the business would not act on. Only used to decide no_material_difference. Choose it BEFORE looking at the result. The default is a software default, not a threshold anyone has endorsed; at a low base rate (say 15%) a smaller margin such as 5 is more sensible. It never suppresses the observed difference.

Required range: 1 <= x <= 50
comparisonsDeclared
integer
default:1

How many comparisons you are making in this analysis, INCLUDING this one. If you are testing 12 use cases to see which wins more, pass 12 on each call: some will look significant by chance, and the verdict corrects for it. Leave at 1 only for a single, pre-planned question.

Required range: 1 <= x <= 1000

Response

Compare Cohorts

_metadata
object
required
definition
object
required

How every number here is defined: what is counted, over which clock, and what is left out. State the relevant parts when quoting a figure.

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
observed
object
required

The descriptive result. ALWAYS reportable, in every verdict state: say which side is higher, by how much and on how many deals. It needs no significance test. What the verdict adds is how far you may go beyond these deals.

exclusions
object
required

Deals that matched but were not compared, by reason. Each deal is counted under one reason.

membershipBasis
object
required

How the compared deals were shown to have a conversation before their outcome, as counts of deals. When most rest on the sync-lag assumption, read timingSensitivity.

timingSensitivity
object
required

The same comparison keeping only deals whose order is KNOWN: still open, or closed at a time the CRM recorded. It drops every deal admitted under the sync-lag assumption or a date-only close, so it is smaller. If the direction changes here, the main result rests on an assumption about timing — say so.

acrossLinkScopes
object
required

The same comparison under each link scope, firmest first. A firmer scope is a smaller and differently selected population, not simply a more correct one: deals a rep attaches activity to in the CRM are not a random sample, and the direction of that difference is not stable.

cohortA
object
required
cohortB
object
required
overlappingDeals
integer
required

Deals that matched BOTH cohorts. They are left out of both arms so the two samples are independent; always 0 when cohort B is 'everything else'.

difference
object
required

The gap between the two sides on the compared outcome, with a 95% interval.

verdict
object
required
sampleNeeded
object
required

Deals with an observable outcome (closed deals, for win_rate) EACH cohort would need to confirm a gap of the size observed (95% confidence, 80% power), next to what the smaller cohort has. When the evidence is insufficient this says how far away an answer is.

stratified
object | null
required

The same comparison made within each value of stratifyBy, then pooled. Null unless stratifyBy was given.

caveats
string[]
required

Things about this data that limit what the numbers support. Read them before quoting.

summary
string
required

The readout in plain words: the observed result, the verdict, and, when a side has no readable outcome, why and which linkScope would read it. Quote counts from the structured fields.

dataWindow
object
required

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

lossReasons
object
required

Each cohort's lost deals by the CRM's own loss reasons (a = cohortA, b = cohortB or every other deal). Ground any claim about why deals were lost in these verbatim reasons.

attribution
object
required

How each compared side's deals were tied to their conversations: deal (a CRM or manual link, or the only deal a conversation reaches) or account (contact-email or domain matching, which also reaches sibling deals), and how many share a conversation with a sibling deal that closed the other way. list_cohort_deals carries the same per deal.

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