> ## 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. # Top Event Entities > Rank the library entities of one type, the values of a tag group, companies, external people, speaker sides or deal stages at the time of the event, across the events matching a window and filters. `metric` picks the ranking; every metric is returned on every item. REST twin of the top_event_entities MCP tool. ## OpenAPI ````yaml post /api/v2/event/top 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/top: post: tags: - Events summary: Top Event Entities description: >- Rank the library entities of one type, the values of a tag group, companies, external people, speaker sides or deal stages at the time of the event, across the events matching a window and filters. `metric` picks the ranking; every metric is returned on every item. REST twin of the top_event_entities MCP tool. operationId: rankEntitiesByEvents requestBody: description: Event window, filters and grouping 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. dimension: type: object properties: by: type: string enum: - segment - persona - use_case - core_feature - competitor - alternative - buying_trigger - objection - proof_point - reference - tag_group - offering - offering_of_core_feature - company - person - speaker_side - deal_stage_at_event description: >- What to group by. A library entity type (use_case, segment, persona, competitor, objection, …) groups by the entities matched on each event. 'tag_group' groups by the values of one tag group (give tagGroupOId) — e.g. use cases rolled up by Imperative. 'company' and 'person' group by who the event was with (person = external contacts). 'offering' groups by the products, services and solutions a finding on the event was matched to directly — the offering was what was talked about. 'offering_of_core_feature' rolls matched CAPABILITIES up to the offering each belongs to in the library today ('(no parent offering)' when a capability has none) — use it to compare products by the capabilities that came up. The two are different relations and give different answers; neither says what a deal SOLD or what the account OWNS. A conversation that touches two offerings counts under both. An offering match classifies the whole conversation rather than quoting someone, so 'offering' crossed with speaker_side is always 'unknown'. 'speaker_side' groups by internal vs external speaker. 'deal_stage_at_event' groups by the CRM stage the linked deal was in WHEN the event happened, not its stage today. tagGroupOId: type: string description: >- Required when by = 'tag_group' (tg_...); ignored otherwise. required: - by metric: type: string enum: - events - uniqueCompanies - uniqueDeals - wonDeals - lostDeals - knownWonValue - winRateSampleAdjusted default: events description: >- What to rank by. events = distinct matching events; uniqueCompanies = distinct companies on them; uniqueDeals / wonDeals / lostDeals = distinct CRM deals linked to them (any / closed-won / closed-lost today); knownWonValue = summed home-currency value of the won deals whose value is known and not negative (a group with none known ranks last); winRateSampleAdjusted = win rate, ranked by the LOW end of each group's 95% interval (`winRate.low`) so a small sample cannot top the list — 2 won of 2 ranks below 40 won of 60. Use it for 'which of these wins most'; the plain `winRate.rate` is on every group but is not offered as a ranking because it rewards tiny samples. Groups with no closed deals rank last. Every metric is returned on every group — this only picks the ordering. limit: type: integer minimum: 1 maximum: 50 default: 10 description: How many to return (default 10, max 50). required: - dimension responses: '200': description: Top Event Entities content: application/json: schema: type: object properties: _metadata: $ref: '#/components/schemas/Metadata' 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. metric: type: string enum: - events - uniqueCompanies - uniqueDeals - wonDeals - lostDeals - knownWonValue - winRateSampleAdjusted description: >- What to rank by. events = distinct matching events; uniqueCompanies = distinct companies on them; uniqueDeals / wonDeals / lostDeals = distinct CRM deals linked to them (any / closed-won / closed-lost today); knownWonValue = summed home-currency value of the won deals whose value is known and not negative (a group with none known ranks last); winRateSampleAdjusted = win rate, ranked by the LOW end of each group's 95% interval (`winRate.low`) so a small sample cannot top the list — 2 won of 2 ranks below 40 won of 60. Use it for 'which of these wins most'; the plain `winRate.rate` is on every group but is not offered as a ranking because it rewards tiny samples. Groups with no closed deals rank last. Every metric is returned on every group — this only picks the ordering. items: type: array items: type: object properties: key: type: string description: >- The group's oId (entity, tag, company, person) or its literal value (side, stage). name: type: string metrics: type: object properties: events: type: integer uniqueCompanies: type: integer uniqueDeals: type: integer wonDeals: type: integer lostDeals: type: integer knownWonValue: type: number nullable: true description: >- Sum of the home-currency values of the won deals whose value is KNOWN and not negative. NOT revenue and not a complete total: read it with wonDealsWithValue, and see wonDealsValueMissing, wonDealsValueUnconverted and negativeValueWonDeals for what it leaves out. Null — never 0 — when no won deal has a known value. It differs from the Insights won-amount figure, which counts unknown values as 0 and nets negative ones. wonDealsWithValue: type: integer description: >- Won deals with a known, non-negative value, a genuine zero included. Below wonDeals, knownWonValue is incomplete. wonDealsValueMissing: type: integer description: Won deals whose CRM value field is empty. wonDealsValueUnconverted: type: integer description: >- Won deals that have a CRM value but no home-currency one: it could not be converted. negativeValueWonDeals: type: object properties: deals: type: integer amount: type: number required: - deals - amount description: >- Won deals carrying a negative value, and their sum, kept out of knownWonValue rather than netted into it. A negative value can be a legitimate adjustment — a CRM amount field that records a change in contract value — not a bad record. winRate: type: object properties: closedDeals: type: integer description: >- Won + lost deals behind the rate. Open deals are not in it. rate: type: number nullable: true description: >- won / closedDeals, 0..1; null with no closed deals. low: type: number nullable: true description: 95% interval, lower bound. high: type: number nullable: true description: 95% interval, upper bound. sampleSizeBand: type: string enum: - insufficient - low - medium - high description: >- Sample-size band only; not confidence in attribution, product alignment, or causality: insufficient (<3 closed deals — do not quote the rate), low (<5), medium (<15), high. Two rates whose intervals overlap heavily are not distinguishable, whatever their point values. required: - closedDeals - rate - low - high - sampleSizeBand description: >- A win rate with its 95% Wilson interval and sample size. Quote the interval, not just the rate, when the sample is small. required: - events - uniqueCompanies - uniqueDeals - wonDeals - lostDeals - knownWonValue - wonDealsWithValue - wonDealsValueMissing - wonDealsValueUnconverted - negativeValueWonDeals - winRate domain: type: string nullable: true description: >- For the company dimension, the company's domain (pass it to find_crm_records or list_pipeline_overview's accountDomain); null when the company has none. Absent for every other dimension. required: - key - name - metrics required: - _metadata - dataWindow - metric - items '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 ````