> ## 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. # Count Events > Count the events matching a date window and filters without returning them: total, a per-channel split, and distinct companies, external people and CRM deals. REST twin of the count_events MCP tool; takes the same window and filters as it and as list_events. ## OpenAPI ````yaml post /api/v2/event/count 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/count: post: tags: - Events summary: Count Events description: >- Count the events matching a date window and filters without returning them: total, a per-channel split, and distinct companies, external people and CRM deals. REST twin of the count_events MCP tool; takes the same window and filters as it and as list_events. operationId: countEvents 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. includePreviousPeriod: type: boolean default: false description: >- Also compute the same thing for the period of equal length immediately before the window, returned under `previous` with its own dataWindow — for 'up or down vs the prior period'. The window's end defaults to now when endDate is omitted. responses: '200': description: Count Events 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. totalEvents: type: integer description: >- Events matching the filters — the same number as list_events' total. byChannel: type: object properties: calls: type: integer messages: type: integer social: type: integer crm: type: integer ads: type: integer resources: type: integer required: - calls - messages - social - crm - ads - resources description: >- totalEvents split by channel. Each count is taken inside the same filters, so with eventTypes restricted to calls every other channel reads 0. uniqueCompanies: type: integer description: >- Distinct companies the matching events are associated with. uniquePeople: type: integer description: >- Distinct EXTERNAL people (resolved contacts) on the matching events. Participants with no contact record are not counted. uniqueDeals: type: integer description: Distinct CRM deals the matching events are linked to. previous: type: object nullable: true properties: 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. totalEvents: type: integer description: >- Events matching the filters — the same number as list_events' total. byChannel: type: object properties: calls: type: integer messages: type: integer social: type: integer crm: type: integer ads: type: integer resources: type: integer required: - calls - messages - social - crm - ads - resources description: >- totalEvents split by channel. Each count is taken inside the same filters, so with eventTypes restricted to calls every other channel reads 0. uniqueCompanies: type: integer description: >- Distinct companies the matching events are associated with. uniquePeople: type: integer description: >- Distinct EXTERNAL people (resolved contacts) on the matching events. Participants with no contact record are not counted. uniqueDeals: type: integer description: Distinct CRM deals the matching events are linked to. required: - dataWindow - totalEvents - byChannel - uniqueCompanies - uniquePeople - uniqueDeals description: >- The same counts for the equal-length period just before the window; null unless includePreviousPeriod was set. required: - _metadata - dataWindow - totalEvents - byChannel - uniqueCompanies - uniquePeople - uniqueDeals - previous '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 ````