> ## Documentation Index > Fetch the complete documentation index at: https://docs.octavehq.com/llms.txt > Use this file to discover all available pages before exploring further. # List Cohort Deals > List the CRM deals on one side of a cohort comparison. Takes the same window, filters and cohorts as Compare Cohorts, plus the side (A, B, or the overlap left out of both), optionally narrowed by dealOutcome or by result on the compared outcome. The returned totals equal that side's counts in the comparison, so the list is exactly what was counted. REST twin of the list_cohort_deals MCP tool. ## OpenAPI ````yaml post /api/v2/event/cohort-deals openapi: 3.0.0 info: version: 5.4.0 title: Octave API description: API for Octave workspace management and AI-powered content generation servers: - url: https://app.octavehq.com security: - ApiKeyAuth: [] paths: /api/v2/event/cohort-deals: post: tags: - Events summary: List Cohort Deals description: >- List the CRM deals on one side of a cohort comparison. Takes the same window, filters and cohorts as Compare Cohorts, plus the side (A, B, or the overlap left out of both), optionally narrowed by dealOutcome or by result on the compared outcome. The returned totals equal that side's counts in the comparison, so the list is exactly what was counted. REST twin of the list_cohort_deals MCP tool. operationId: listCohortDeals requestBody: description: Event window, shared filters, the two cohorts and the side to list content: application/json: schema: type: object properties: startDate: type: string nullable: true format: date-time description: >- 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: type: string nullable: true format: date-time description: >- 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: type: object properties: entityMatchAll: type: boolean description: >- Require every selected library entity, including entities of the same category eventOIds: type: array items: type: string description: Filter to these event oIds only opportunityIds: type: array items: type: string description: >- Filter to events linked to these opportunities. Accepts Octave opportunity oIds (crmo_*) or the CRM's own deal ids (Salesforce Id, HubSpot object id, Attio record UUID) interchangeably eventCategories: type: array items: type: string enum: - EMAIL - CALL - CRM - RESOURCE - REVISION - SOCIAL - ADS - PRODUCT - UNKNOWN description: Filter by event categories (CALL, EMAIL, CRM) eventTypes: type: array items: type: string enum: - EMAIL_SENT - EMAIL_REPLY_RECEIVED - CALL_TRANSCRIPT - DEAL_WON - DEAL_LOST - OPPORTUNITY_CREATED - MEETING_BOOKED - RESOURCE_INDEXED - RESOURCE_REINDEXED - PROJECT_UPDATE - TASK_COMPLETED - ENTITY_CREATED - ENTITY_UPDATED - SOCIAL_MESSAGE_SENT - SOCIAL_MESSAGE_RECEIVED - SOCIAL_CONNECTION_SENT - SOCIAL_CONNECTION_ACCEPTED - AD_SET_PUBLISHED - AD_PERFORMANCE_SNAPSHOT - BULK_IMPORT_SUMMARY - PROCESSING_NOT_APPLICABLE - PROVIDER_EVENT_TYPE_UNKNOWN - UNKNOWN description: >- Filter by specific event types (CALL_TRANSCRIPT, EMAIL_SENT, DEAL_WON, etc.) sentiments: type: array items: type: string enum: - POSITIVE - NEUTRAL - NEGATIVE - UNKNOWN description: Filter by sentiment (POSITIVE, NEGATIVE, NEUTRAL, MIXED) contactEmails: type: array items: type: string description: Filter by participant email addresses companyDomains: type: array items: type: string description: Filter by company domains outcomeFilters: type: array items: type: string enum: - OPEN - WON - LOST - POSITIVE_REPLY - NEUTRAL_REPLY - NEGATIVE_REPLY description: >- Filter by outcome (OPEN, WON, LOST, POSITIVE_REPLY, NEUTRAL_REPLY, NEGATIVE_REPLY) opportunityStatuses: type: array items: type: string enum: - OPEN - WON - LOST description: >- Filter to events linked to deals with this status (OPEN, WON, LOST) dealMotions: type: array items: type: string enum: - NET_NEW - UPSELL - CROSS_SELL - RENEW_AND_RETAIN - CONVERT_FREE_TO_PAID - DISPLACE_INCUMBENT - SERVICES - PARTNER - NON_COMMERCIAL description: >- Filter to events linked to deals whose CRM deal type maps to these motions (NET_NEW, UPSELL, CROSS_SELL, RENEW_AND_RETAIN, CONVERT_FREE_TO_PAID, DISPLACE_INCUMBENT, SERVICES, PARTNER, NON_COMMERCIAL) dealTypes: type: array items: type: string description: >- Filter to events linked to deals with these raw CRM deal-type labels (Salesforce Type, HubSpot dealtype), case-insensitive dealStages: type: array items: type: string description: >- Filter to events linked to deals currently in these CRM stages, by stage label or stage id, case-insensitive dealStagesAtEvent: type: array items: type: string description: >- Filter to events whose linked deal was in one of these CRM stages WHEN THE EVENT HAPPENED (by stage label, case-insensitive), from the deal's stage history — unlike dealStages, which reads the deal's stage today. Use it for 'what came up on calls during Discovery'. An event whose deal has no recorded stage at that time does not match. pipelinePhases: type: array items: type: string enum: - prospecting - discovery - evaluation - negotiation - commitment - closed_won - closed_lost description: >- Filter to events linked to deals whose stage maps to these pipeline phases (prospecting, discovery, evaluation, negotiation, commitment, closed_won, closed_lost) crmPipelines: type: array items: type: string description: >- Filter to events linked to deals in these CRM pipelines, by pipeline id or name (case-insensitive name) minStalledDays: type: number description: >- Filter to events linked to an OPEN deal that has sat in its current stage at least this many days minDealAmount: type: number description: Minimum deal amount filter maxDealAmount: type: number description: Maximum deal amount filter offerings: type: array items: type: string description: Filter by offering oIds personas: type: array items: type: string description: >- Filter by persona oIds (events must match these personas) segments: type: array items: type: string description: Filter by segment oIds tags: type: array items: type: string description: >- Filter by reporting tag oIds (from any tag group, on any library entity type). Resolved to the entities carrying those tags; multiple tags are OR'd. useCases: type: array items: type: string description: Filter by use case oIds references: type: array items: type: string description: Filter by reference customer oIds competitors: type: array items: type: string description: Filter by competitor oIds alternatives: type: array items: type: string description: Filter by alternative oIds buyingTriggers: type: array items: type: string description: Filter by buying trigger oIds coreFeatures: type: array items: type: string description: Filter by core feature oIds objections: type: array items: type: string description: Filter by objection oIds proofPoints: type: array items: type: string description: Filter by proof point oIds motionTypes: type: array items: type: string enum: - NET_NEW - UPSELL - CROSS_SELL - CONVERT_FREE_TO_PAID - RENEW_AND_RETAIN - DISPLACE_INCUMBENT description: Filter by motion type (NET_NEW, UPSELL) customerScope: type: string enum: - ALL - NEW_CUSTOMERS - EXISTING_CUSTOMERS description: >- Customer-scope view (NEW_CUSTOMERS / EXISTING_CUSTOMERS); ALL or absent applies no filter callPurposes: type: array items: type: string enum: - DISCOVERY - DEMO - TECHNICAL_EVALUATION - WORKING_SESSION - NEGOTIATION_PRICING - ONBOARDING - CHECK_IN_SUCCESS - QBR_RENEWAL - EXPANSION_UPSELL - ESCALATION_CHURN_RISK - SUPPORT - INTERNAL_SYNC - OTHER description: >- Filter calls by classified purpose (DISCOVERY, DEMO, TECHNICAL_EVALUATION, WORKING_SESSION, NEGOTIATION_PRICING, ONBOARDING, CHECK_IN_SUCCESS, QBR_RENEWAL, EXPANSION_UPSELL, ESCALATION_CHURN_RISK, SUPPORT, INTERNAL_SYNC, OTHER) unmatchedOnly: type: boolean description: >- When true, only return events that have findings with no library entity matches description: >- 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, 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. exclude: type: object properties: eventCategories: type: array items: type: string enum: - EMAIL - CALL - CRM - RESOURCE - REVISION - SOCIAL - ADS - PRODUCT - UNKNOWN description: Filter by event categories (CALL, EMAIL, CRM) eventTypes: type: array items: type: string enum: - EMAIL_SENT - EMAIL_REPLY_RECEIVED - CALL_TRANSCRIPT - DEAL_WON - DEAL_LOST - OPPORTUNITY_CREATED - MEETING_BOOKED - RESOURCE_INDEXED - RESOURCE_REINDEXED - PROJECT_UPDATE - TASK_COMPLETED - ENTITY_CREATED - ENTITY_UPDATED - SOCIAL_MESSAGE_SENT - SOCIAL_MESSAGE_RECEIVED - SOCIAL_CONNECTION_SENT - SOCIAL_CONNECTION_ACCEPTED - AD_SET_PUBLISHED - AD_PERFORMANCE_SNAPSHOT - BULK_IMPORT_SUMMARY - PROCESSING_NOT_APPLICABLE - PROVIDER_EVENT_TYPE_UNKNOWN - UNKNOWN description: >- Filter by specific event types (CALL_TRANSCRIPT, EMAIL_SENT, DEAL_WON, etc.) sentiments: type: array items: type: string enum: - POSITIVE - NEUTRAL - NEGATIVE - UNKNOWN description: Filter by sentiment (POSITIVE, NEGATIVE, NEUTRAL, MIXED) contactEmails: type: array items: type: string description: Filter by participant email addresses companyDomains: type: array items: type: string description: Filter by company domains outcomeFilters: type: array items: type: string enum: - OPEN - WON - LOST - POSITIVE_REPLY - NEUTRAL_REPLY - NEGATIVE_REPLY description: >- Exclude by outcome (OPEN, WON, LOST, POSITIVE_REPLY, NEUTRAL_REPLY, NEGATIVE_REPLY) opportunityStatuses: type: array items: type: string enum: - OPEN - WON - LOST description: Exclude by opportunity status (OPEN, WON, LOST) minDealAmount: type: number description: Minimum deal amount filter maxDealAmount: type: number description: Maximum deal amount filter offerings: type: array items: type: string description: Exclude events matching these offering oIds personas: type: array items: type: string description: Exclude events matching these persona oIds segments: type: array items: type: string description: Exclude events matching these segment oIds tags: type: array items: type: string description: >- Exclude events matching any library entity that carries these reporting tag oIds (any tag group; OR'd). useCases: type: array items: type: string description: Exclude events matching these use case oIds references: type: array items: type: string description: Exclude events matching these reference customer oIds competitors: type: array items: type: string description: Exclude events matching these competitor oIds alternatives: type: array items: type: string description: Exclude events matching these alternative oIds buyingTriggers: type: array items: type: string description: Exclude events matching these buying trigger oIds coreFeatures: type: array items: type: string description: Exclude events matching these core feature oIds objections: type: array items: type: string description: Exclude events matching these objection oIds proofPoints: type: array items: type: string description: Exclude events matching these proof point oIds motionTypes: type: array items: type: string enum: - NET_NEW - UPSELL - CROSS_SELL - CONVERT_FREE_TO_PAID - RENEW_AND_RETAIN - DISPLACE_INCUMBENT description: >- Exclude events matching these motion types (NET_NEW, UPSELL) callPurposes: type: array items: type: string enum: - DISCOVERY - DEMO - TECHNICAL_EVALUATION - WORKING_SESSION - NEGOTIATION_PRICING - ONBOARDING - CHECK_IN_SUCCESS - QBR_RENEWAL - EXPANSION_UPSELL - ESCALATION_CHURN_RISK - SUPPORT - INTERNAL_SYNC - OTHER description: >- Exclude calls with these classified purposes (e.g. SUPPORT, INTERNAL_SYNC) dealMotions: type: array items: type: string enum: - NET_NEW - UPSELL - CROSS_SELL - RENEW_AND_RETAIN - CONVERT_FREE_TO_PAID - DISPLACE_INCUMBENT - SERVICES - PARTNER - NON_COMMERCIAL description: >- Exclude events linked to deals whose CRM deal type maps to these motions dealTypes: type: array items: type: string description: >- Exclude events linked to deals with these raw CRM deal-type labels, case-insensitive dealStages: type: array items: type: string description: >- Exclude events linked to deals currently in these CRM stages, by stage label or stage id, case-insensitive pipelinePhases: type: array items: type: string enum: - prospecting - discovery - evaluation - negotiation - commitment - closed_won - closed_lost description: >- Exclude events linked to deals whose stage maps to these pipeline phases description: >- Filters to EXCLUDE events matching these criteria (same shape as the entity/outcome match filters) excludeTags: type: array items: type: string description: >- 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. cohortA: type: object properties: label: type: string minLength: 1 description: Short name used in the verdict, e.g. 'Intake mentioned'. filters: type: object properties: entityMatchAll: type: boolean description: >- Require every selected library entity, including entities of the same category eventOIds: type: array items: type: string description: Filter to these event oIds only opportunityIds: type: array items: type: string description: >- Filter to events linked to these opportunities. Accepts Octave opportunity oIds (crmo_*) or the CRM's own deal ids (Salesforce Id, HubSpot object id, Attio record UUID) interchangeably eventCategories: type: array items: type: string enum: - EMAIL - CALL - CRM - RESOURCE - REVISION - SOCIAL - ADS - PRODUCT - UNKNOWN description: Filter by event categories (CALL, EMAIL, CRM) eventTypes: type: array items: type: string enum: - EMAIL_SENT - EMAIL_REPLY_RECEIVED - CALL_TRANSCRIPT - DEAL_WON - DEAL_LOST - OPPORTUNITY_CREATED - MEETING_BOOKED - RESOURCE_INDEXED - RESOURCE_REINDEXED - PROJECT_UPDATE - TASK_COMPLETED - ENTITY_CREATED - ENTITY_UPDATED - SOCIAL_MESSAGE_SENT - SOCIAL_MESSAGE_RECEIVED - SOCIAL_CONNECTION_SENT - SOCIAL_CONNECTION_ACCEPTED - AD_SET_PUBLISHED - AD_PERFORMANCE_SNAPSHOT - BULK_IMPORT_SUMMARY - PROCESSING_NOT_APPLICABLE - PROVIDER_EVENT_TYPE_UNKNOWN - UNKNOWN description: >- Filter by specific event types (CALL_TRANSCRIPT, EMAIL_SENT, DEAL_WON, etc.) sentiments: type: array items: type: string enum: - POSITIVE - NEUTRAL - NEGATIVE - UNKNOWN description: >- Filter by sentiment (POSITIVE, NEGATIVE, NEUTRAL, MIXED) contactEmails: type: array items: type: string description: Filter by participant email addresses companyDomains: type: array items: type: string description: Filter by company domains outcomeFilters: type: array items: type: string enum: - OPEN - WON - LOST - POSITIVE_REPLY - NEUTRAL_REPLY - NEGATIVE_REPLY description: >- Filter by outcome (OPEN, WON, LOST, POSITIVE_REPLY, NEUTRAL_REPLY, NEGATIVE_REPLY) opportunityStatuses: type: array items: type: string enum: - OPEN - WON - LOST description: >- Filter to events linked to deals with this status (OPEN, WON, LOST) dealMotions: type: array items: type: string enum: - NET_NEW - UPSELL - CROSS_SELL - RENEW_AND_RETAIN - CONVERT_FREE_TO_PAID - DISPLACE_INCUMBENT - SERVICES - PARTNER - NON_COMMERCIAL description: >- Filter to events linked to deals whose CRM deal type maps to these motions (NET_NEW, UPSELL, CROSS_SELL, RENEW_AND_RETAIN, CONVERT_FREE_TO_PAID, DISPLACE_INCUMBENT, SERVICES, PARTNER, NON_COMMERCIAL) dealTypes: type: array items: type: string description: >- Filter to events linked to deals with these raw CRM deal-type labels (Salesforce Type, HubSpot dealtype), case-insensitive dealStages: type: array items: type: string description: >- Filter to events linked to deals currently in these CRM stages, by stage label or stage id, case-insensitive dealStagesAtEvent: type: array items: type: string description: >- Filter to events whose linked deal was in one of these CRM stages WHEN THE EVENT HAPPENED (by stage label, case-insensitive), from the deal's stage history — unlike dealStages, which reads the deal's stage today. Use it for 'what came up on calls during Discovery'. An event whose deal has no recorded stage at that time does not match. pipelinePhases: type: array items: type: string enum: - prospecting - discovery - evaluation - negotiation - commitment - closed_won - closed_lost description: >- Filter to events linked to deals whose stage maps to these pipeline phases (prospecting, discovery, evaluation, negotiation, commitment, closed_won, closed_lost) crmPipelines: type: array items: type: string description: >- Filter to events linked to deals in these CRM pipelines, by pipeline id or name (case-insensitive name) minStalledDays: type: number description: >- Filter to events linked to an OPEN deal that has sat in its current stage at least this many days minDealAmount: type: number description: Minimum deal amount filter maxDealAmount: type: number description: Maximum deal amount filter offerings: type: array items: type: string description: Filter by offering oIds personas: type: array items: type: string description: >- Filter by persona oIds (events must match these personas) segments: type: array items: type: string description: Filter by segment oIds tags: type: array items: type: string description: >- Filter by reporting tag oIds (from any tag group, on any library entity type). Resolved to the entities carrying those tags; multiple tags are OR'd. useCases: type: array items: type: string description: Filter by use case oIds references: type: array items: type: string description: Filter by reference customer oIds competitors: type: array items: type: string description: Filter by competitor oIds alternatives: type: array items: type: string description: Filter by alternative oIds buyingTriggers: type: array items: type: string description: Filter by buying trigger oIds coreFeatures: type: array items: type: string description: Filter by core feature oIds objections: type: array items: type: string description: Filter by objection oIds proofPoints: type: array items: type: string description: Filter by proof point oIds motionTypes: type: array items: type: string enum: - NET_NEW - UPSELL - CROSS_SELL - CONVERT_FREE_TO_PAID - RENEW_AND_RETAIN - DISPLACE_INCUMBENT description: Filter by motion type (NET_NEW, UPSELL) customerScope: type: string enum: - ALL - NEW_CUSTOMERS - EXISTING_CUSTOMERS description: >- Customer-scope view (NEW_CUSTOMERS / EXISTING_CUSTOMERS); ALL or absent applies no filter callPurposes: type: array items: type: string enum: - DISCOVERY - DEMO - TECHNICAL_EVALUATION - WORKING_SESSION - NEGOTIATION_PRICING - ONBOARDING - CHECK_IN_SUCCESS - QBR_RENEWAL - EXPANSION_UPSELL - ESCALATION_CHURN_RISK - SUPPORT - INTERNAL_SYNC - OTHER description: >- Filter calls by classified purpose (DISCOVERY, DEMO, TECHNICAL_EVALUATION, WORKING_SESSION, NEGOTIATION_PRICING, ONBOARDING, CHECK_IN_SUCCESS, QBR_RENEWAL, EXPANSION_UPSELL, ESCALATION_CHURN_RISK, SUPPORT, INTERNAL_SYNC, OTHER) unmatchedOnly: type: boolean description: >- When true, only return events that have findings with no library entity matches description: >- What puts a deal in this cohort: event filters, ANDed with the shared `filters`. A deal belongs if ANY of its events in the window match — e.g. { useCases: ['uc_…'] } is 'deals where this use case came up'. required: - label cohortB: type: object properties: label: type: string minLength: 1 description: Short name used in the verdict, e.g. 'Intake mentioned'. filters: type: object properties: entityMatchAll: type: boolean description: >- Require every selected library entity, including entities of the same category eventOIds: type: array items: type: string description: Filter to these event oIds only opportunityIds: type: array items: type: string description: >- Filter to events linked to these opportunities. Accepts Octave opportunity oIds (crmo_*) or the CRM's own deal ids (Salesforce Id, HubSpot object id, Attio record UUID) interchangeably eventCategories: type: array items: type: string enum: - EMAIL - CALL - CRM - RESOURCE - REVISION - SOCIAL - ADS - PRODUCT - UNKNOWN description: Filter by event categories (CALL, EMAIL, CRM) eventTypes: type: array items: type: string enum: - EMAIL_SENT - EMAIL_REPLY_RECEIVED - CALL_TRANSCRIPT - DEAL_WON - DEAL_LOST - OPPORTUNITY_CREATED - MEETING_BOOKED - RESOURCE_INDEXED - RESOURCE_REINDEXED - PROJECT_UPDATE - TASK_COMPLETED - ENTITY_CREATED - ENTITY_UPDATED - SOCIAL_MESSAGE_SENT - SOCIAL_MESSAGE_RECEIVED - SOCIAL_CONNECTION_SENT - SOCIAL_CONNECTION_ACCEPTED - AD_SET_PUBLISHED - AD_PERFORMANCE_SNAPSHOT - BULK_IMPORT_SUMMARY - PROCESSING_NOT_APPLICABLE - PROVIDER_EVENT_TYPE_UNKNOWN - UNKNOWN description: >- Filter by specific event types (CALL_TRANSCRIPT, EMAIL_SENT, DEAL_WON, etc.) sentiments: type: array items: type: string enum: - POSITIVE - NEUTRAL - NEGATIVE - UNKNOWN description: >- Filter by sentiment (POSITIVE, NEGATIVE, NEUTRAL, MIXED) contactEmails: type: array items: type: string description: Filter by participant email addresses companyDomains: type: array items: type: string description: Filter by company domains outcomeFilters: type: array items: type: string enum: - OPEN - WON - LOST - POSITIVE_REPLY - NEUTRAL_REPLY - NEGATIVE_REPLY description: >- Filter by outcome (OPEN, WON, LOST, POSITIVE_REPLY, NEUTRAL_REPLY, NEGATIVE_REPLY) opportunityStatuses: type: array items: type: string enum: - OPEN - WON - LOST description: >- Filter to events linked to deals with this status (OPEN, WON, LOST) dealMotions: type: array items: type: string enum: - NET_NEW - UPSELL - CROSS_SELL - RENEW_AND_RETAIN - CONVERT_FREE_TO_PAID - DISPLACE_INCUMBENT - SERVICES - PARTNER - NON_COMMERCIAL description: >- Filter to events linked to deals whose CRM deal type maps to these motions (NET_NEW, UPSELL, CROSS_SELL, RENEW_AND_RETAIN, CONVERT_FREE_TO_PAID, DISPLACE_INCUMBENT, SERVICES, PARTNER, NON_COMMERCIAL) dealTypes: type: array items: type: string description: >- Filter to events linked to deals with these raw CRM deal-type labels (Salesforce Type, HubSpot dealtype), case-insensitive dealStages: type: array items: type: string description: >- Filter to events linked to deals currently in these CRM stages, by stage label or stage id, case-insensitive dealStagesAtEvent: type: array items: type: string description: >- Filter to events whose linked deal was in one of these CRM stages WHEN THE EVENT HAPPENED (by stage label, case-insensitive), from the deal's stage history — unlike dealStages, which reads the deal's stage today. Use it for 'what came up on calls during Discovery'. An event whose deal has no recorded stage at that time does not match. pipelinePhases: type: array items: type: string enum: - prospecting - discovery - evaluation - negotiation - commitment - closed_won - closed_lost description: >- Filter to events linked to deals whose stage maps to these pipeline phases (prospecting, discovery, evaluation, negotiation, commitment, closed_won, closed_lost) crmPipelines: type: array items: type: string description: >- Filter to events linked to deals in these CRM pipelines, by pipeline id or name (case-insensitive name) minStalledDays: type: number description: >- Filter to events linked to an OPEN deal that has sat in its current stage at least this many days minDealAmount: type: number description: Minimum deal amount filter maxDealAmount: type: number description: Maximum deal amount filter offerings: type: array items: type: string description: Filter by offering oIds personas: type: array items: type: string description: >- Filter by persona oIds (events must match these personas) segments: type: array items: type: string description: Filter by segment oIds tags: type: array items: type: string description: >- Filter by reporting tag oIds (from any tag group, on any library entity type). Resolved to the entities carrying those tags; multiple tags are OR'd. useCases: type: array items: type: string description: Filter by use case oIds references: type: array items: type: string description: Filter by reference customer oIds competitors: type: array items: type: string description: Filter by competitor oIds alternatives: type: array items: type: string description: Filter by alternative oIds buyingTriggers: type: array items: type: string description: Filter by buying trigger oIds coreFeatures: type: array items: type: string description: Filter by core feature oIds objections: type: array items: type: string description: Filter by objection oIds proofPoints: type: array items: type: string description: Filter by proof point oIds motionTypes: type: array items: type: string enum: - NET_NEW - UPSELL - CROSS_SELL - CONVERT_FREE_TO_PAID - RENEW_AND_RETAIN - DISPLACE_INCUMBENT description: Filter by motion type (NET_NEW, UPSELL) customerScope: type: string enum: - ALL - NEW_CUSTOMERS - EXISTING_CUSTOMERS description: >- Customer-scope view (NEW_CUSTOMERS / EXISTING_CUSTOMERS); ALL or absent applies no filter callPurposes: type: array items: type: string enum: - DISCOVERY - DEMO - TECHNICAL_EVALUATION - WORKING_SESSION - NEGOTIATION_PRICING - ONBOARDING - CHECK_IN_SUCCESS - QBR_RENEWAL - EXPANSION_UPSELL - ESCALATION_CHURN_RISK - SUPPORT - INTERNAL_SYNC - OTHER description: >- Filter calls by classified purpose (DISCOVERY, DEMO, TECHNICAL_EVALUATION, WORKING_SESSION, NEGOTIATION_PRICING, ONBOARDING, CHECK_IN_SUCCESS, QBR_RENEWAL, EXPANSION_UPSELL, ESCALATION_CHURN_RISK, SUPPORT, INTERNAL_SYNC, OTHER) unmatchedOnly: type: boolean description: >- When true, only return events that have findings with no library entity matches description: >- What puts a deal in this cohort: event filters, ANDed with the shared `filters`. A deal belongs if ANY of its events in the window match — e.g. { useCases: ['uc_…'] } is 'deals where this use case came up'. required: - label description: >- 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?'). outcome: oneOf: - type: object properties: metric: type: string enum: - win_rate required: - metric - type: object properties: metric: type: string enum: - advanced_within_days days: type: integer minimum: 7 maximum: 180 default: 30 description: >- How long after the conversation the deal has to move. required: - metric - type: object properties: metric: type: string enum: - faster_than_stage_median required: - metric - type: object properties: metric: type: string enum: - next_conversation_positive required: - metric default: metric: win_rate description: >- 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: type: string enum: - crm_linked - single_candidate - outcome_attribution - account_associated description: >- 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. It includes a conversation matched by email to every deal its contact sits on, so on accounts with many open deals a cohort is 'deals at accounts where this came up' more than 'deals where it came up'. 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. account_associated: every link. The response reports the comparison under all four (acrossLinkScopes), so you can see whether the direction holds. side: type: string enum: - A - B - overlap - excluded description: >- 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). dealOutcome: type: string enum: - won - lost - open description: >- 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. result: type: string enum: - success - failure - not_observable description: >- Only deals with this result on the compared `outcome`, e.g. 'failure' with outcome advanced_within_days for the deals that did not move. limit: type: integer minimum: 1 maximum: 100 default: 25 cursor: type: string description: nextCursor from the previous page. required: - cohortA - side responses: '200': description: List Cohort Deals content: application/json: schema: type: object properties: _metadata: $ref: '#/components/schemas/Metadata' side: type: string enum: - A - B - overlap - excluded label: type: string totals: type: object properties: deals: type: integer wonDeals: type: integer lostDeals: type: integer openDeals: type: integer successes: type: integer failures: type: integer notObservable: type: integer required: - deals - wonDeals - lostDeals - openDeals - successes - failures - notObservable description: >- 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: type: integer description: >- Deals on this side left after the `dealOutcome` and `result` filters, before paging. Equal to totalDeals when neither is given. deals: type: array items: type: object properties: opportunityOId: type: string description: >- Octave oId of the CRM deal (crmo_…). Pass it as filters.opportunityIds to list_events or list_findings, with the same window and cohort filters, for the conversations behind this deal. name: type: string outcome: type: string enum: - won - lost - open description: How the deal stands in the CRM today. result: type: string enum: - success - failure - not_observable description: >- How the deal came out on the compared `outcome`. For win_rate: won is success, lost is failure, open is not_observable. linkTier: type: string enum: - crm_linked - single_candidate - outcome_attribution - account_associated description: >- The firmest link tying a matching conversation to this deal: crm_linked, single_candidate, outcome_attribution or account_associated. excludedBecause: type: string nullable: true enum: - post_outcome_only - order_unknown - reopened - ambiguous_exposure - null description: >- Side 'excluded' only: why the deal matched but was not compared. Null on every other side. stageName: type: string nullable: true description: The deal's CRM stage today. amount: type: number nullable: true description: >- Deal value in the workspace's home currency; null when the CRM value is missing or could not be converted. Can be negative where the CRM amount records a change in contract value. matchingEvents: type: integer description: >- Events in the window that matched this side's filters and link to the deal — why it is in the cohort. lastMatchingEventAt: type: string description: ISO 8601. required: - opportunityOId - name - outcome - result - linkTier - excludedBecause - stageName - amount - matchingEvents - lastMatchingEventAt nextCursor: type: string nullable: true description: Pass as `cursor` for the next page; null on the last one. dataWindow: type: object properties: kind: type: string enum: - event_range - stats_period startDate: type: string nullable: true description: >- Inclusive start (ISO). Null only when no data exists yet. endDate: type: string nullable: true description: >- End (ISO). An event_range with no endDate given ends at the time of the request. isDefault: type: boolean description: >- True when the caller did not choose this window and the tool's default applied. periodType: type: string nullable: true enum: - week - month - quarter - null description: >- week / month / quarter for a stats_period; null otherwise. required: - kind - startDate - endDate - isDefault - periodType description: >- The time span these numbers cover. Compare numbers from two tools only when their dataWindow kind and dates match. linkScope: type: string enum: - crm_linked - single_candidate - outcome_attribution - account_associated description: >- 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. It includes a conversation matched by email to every deal its contact sits on, so on accounts with many open deals a cohort is 'deals at accounts where this came up' more than 'deals where it came up'. 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. account_associated: every link. The response reports the comparison under all four (acrossLinkScopes), so you can see whether the direction holds. linkScopeSource: type: string enum: - request - workspace_default - product_default description: >- 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. required: - _metadata - side - label - totals - matchingDeals - deals - nextCursor - dataWindow - linkScope - linkScopeSource '400': description: Bad request content: application/json: schema: type: object properties: _metadata: $ref: '#/components/schemas/Metadata' message: type: string required: - _metadata - message deprecated: false components: schemas: Metadata: type: object properties: usage: type: number default: 0 example: 0 description: API usage requestId: type: string example: requestId description: Request ID message: type: string example: message description: Message timestamp: type: string example: '2021-01-01T00:00:00.000Z' description: Timestamp required: - requestId - timestamp securitySchemes: ApiKeyAuth: type: apiKey in: header name: api_key ````