> ## 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. # Search Findings > Search extracted findings from sales conversations using natural language. Findings are insights extracted from calls, emails, and other events — objections, pain points, competitor mentions, value props, and more. Describe what you're looking for (the query is translated to finding types), or pass customExtractorOIds for an exact filter on workspace-defined extractors. Optionally narrow by event type, company, deal outcome, call purpose, linked entities, or the persona cohort that SPOKE the finding. Each row carries its event/company linkage, compact persisted evidence (quote, reasoning, speaker label), and the resolved attributed participant — use /event/get to pull a finding's full transcript or email. ## OpenAPI ````yaml post /api/v2/finding/search 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/finding/search: post: tags: - Findings summary: Search Findings description: >- Search extracted findings from sales conversations using natural language. Findings are insights extracted from calls, emails, and other events — objections, pain points, competitor mentions, value props, and more. Describe what you're looking for (the query is translated to finding types), or pass customExtractorOIds for an exact filter on workspace-defined extractors. Optionally narrow by event type, company, deal outcome, call purpose, linked entities, or the persona cohort that SPOKE the finding. Each row carries its event/company linkage, compact persisted evidence (quote, reasoning, speaker label), and the resolved attributed participant — use /event/get to pull a finding's full transcript or email. operationId: searchFindings requestBody: description: Findings search query and filters content: application/json: schema: type: object properties: query: type: string description: >- Natural language description of what findings you want, e.g. 'objections from prospects', 'pricing concerns from lost deals'. Required unless customExtractorOIds is provided. example: objections from prospects customExtractorOIds: type: array items: type: string description: >- Filter to findings produced by these workspace-defined custom extractors (oIds, as returned in each finding's customExtractor field). Exact filter — when provided, natural-language translation of the query is skipped and only these extractors' findings are returned. 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. example: '2026-08-01T00:00:00Z' endDate: type: string nullable: true format: date-time description: >- End date for event time range (optional; if omitted, no upper bound is applied) eventFilters: $ref: '#/components/schemas/FindingSearchEventFilters' speakerSide: type: string enum: - internal - external description: >- Who said it: 'external' is the buyer's side, 'internal' the workspace's own people. Narrows a query to that side, or, given alone, returns every finding type from that side. The side is read per finding (its recorded speaker, a custom extractor's perspective, the participant it was attributed to), so it combines with customExtractorOIds. Findings nothing attributes to a speaker, and document findings, match neither side. example: external attributedPersonaOIds: type: array items: type: string description: >- Filter to findings SPOKEN BY contacts classified into these personas (e.g. 'objections raised by CTOs'). Different from eventFilters.personas, which matches findings TAGGED with a persona. Attribution exists only for email and call findings with a resolved speaker. insightOId: type: string description: >- Scope results to one Insight: only findings from the events that Insight covers, resolved the same way the Insight's own run resolves them. Given alone, it also selects the finding types and custom extractors the Insight reads. Combined with query or customExtractorOIds, it narrows the events only and your own source selection is kept. example: rcfg_XVPcS3dLZFqzfQIfSeCpk limit: type: integer minimum: 1 maximum: 200 default: 100 description: 'Maximum results to return (default: 100, max: 200)' example: 100 offset: type: integer minimum: 0 default: 0 description: Offset for pagination responses: '200': description: Matching findings with pagination info content: application/json: schema: type: object properties: _metadata: $ref: '#/components/schemas/Metadata' findings: type: array items: $ref: '#/components/schemas/FindingSearchResult' description: >- Matching findings, each with its event/company/speaker linkage total: type: number hasMore: type: boolean 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. required: - _metadata - findings - total - hasMore - dataWindow '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: FindingSearchEventFilters: type: object properties: 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 event types (CALL_TRANSCRIPT, EMAIL_SENT, etc.) eventCategories: type: array items: type: string enum: - EMAIL - CALL - CRM - RESOURCE - REVISION - SOCIAL - ADS - PRODUCT - UNKNOWN description: Filter by event categories (CALL, EMAIL, CRM) companyDomains: type: array items: type: string description: Filter by company domains (e.g., ['acme.com', 'contoso.com']) contactEmails: type: array items: type: string description: Filter by participant email addresses outcomeFilters: type: array items: type: string enum: - OPEN - WON - LOST - POSITIVE_REPLY - NEUTRAL_REPLY - NEGATIVE_REPLY description: >- Filter by deal outcome: OPEN, WON, LOST, POSITIVE_REPLY, NEGATIVE_REPLY minDealAmount: type: number description: Minimum deal amount maxDealAmount: type: number description: Maximum deal amount sentiments: type: array items: type: string enum: - POSITIVE - NEUTRAL - NEGATIVE - UNKNOWN description: Filter by sentiment (POSITIVE, NEGATIVE, NEUTRAL, MIXED) 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 to findings from calls classified with any of these purposes (OR). Only call events carry a purpose, so this also narrows results to calls. personas: type: array items: type: string description: Filter by persona oIds playbooks: type: array items: type: string description: Filter by playbook oIds competitors: type: array items: type: string description: Filter by competitor oIds segments: type: array items: type: string description: Filter by segment oIds useCases: type: array items: type: string description: Filter by use case oIds references: type: array items: type: string description: Filter by reference customer oIds proofPoints: type: array items: type: string description: Filter by proof point oIds description: Additional filters to narrow down which events to search 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 FindingSearchResult: type: object properties: oId: type: string snippetText: type: string extractionType: type: string enum: - EMAIL_INTERNAL_USE_CASE - EMAIL_INTERNAL_PROOF_POINT - EMAIL_INTERNAL_PAIN_POINT - EMAIL_INTERNAL_BENEFITS_HIGHLIGHTED - EMAIL_INTERNAL_VALUE_PROP - EMAIL_INTERNAL_SOCIAL_PROOF - EMAIL_INTERNAL_CALL_TO_ACTION - EMAIL_INTERNAL_OBJECTION_HANDLING - EMAIL_INTERNAL_COMPETITORS_TO_OUR_OFFERING - EMAIL_INTERNAL_CORE_CAPABILITIES - EMAIL_INTERNAL_DIFFERENTIATED_VALUE - EMAIL_INTERNAL_COMPLEMENTARY_TOOLS_MENTIONED - EMAIL_INTERNAL_BUYING_TRIGGER_CITED - EMAIL_INTERNAL_COMMITMENTS_MADE - EMAIL_EXTERNAL_CALL_TO_ACTION - EMAIL_EXTERNAL_OBJECTION - EMAIL_EXTERNAL_QUESTION - EMAIL_EXTERNAL_INTEREST_EXPRESSION - EMAIL_EXTERNAL_FEATURE_REQUEST - EMAIL_EXTERNAL_REQUIREMENT - EMAIL_EXTERNAL_PRICING_FEEDBACK - EMAIL_EXTERNAL_COMPARATIVE_STATEMENT - EMAIL_EXTERNAL_KEY_TAKEAWAY - EMAIL_EXTERNAL_COMPETITOR_MENTION - EMAIL_EXTERNAL_NEXT_STEP - EMAIL_EXTERNAL_URGENCY_INDICATOR - EMAIL_EXTERNAL_DECISION_MAKING_SIGNAL - EMAIL_EXTERNAL_UNIQUE_LANGUAGE_USED - EMAIL_EXTERNAL_BUSINESS_PROBLEMS - EMAIL_EXTERNAL_PRIMARY_GOALS - EMAIL_EXTERNAL_STATUS_QUO_HOW_THEY_SOLVE_TODAY - EMAIL_EXTERNAL_CURRENT_TOOL_OR_SOLUTION_PROBLEMS - EMAIL_EXTERNAL_PAIN_OR_PROBLEM_AGREEMENTS - EMAIL_EXTERNAL_ROLE_OR_RESPONSIBILITIES_DESCRIPTION - EMAIL_EXTERNAL_CORE_CAPABILITIES - EMAIL_EXTERNAL_USE_CASES_BROUGHT_UP - EMAIL_EXTERNAL_BLOCKERS_OR_DEPENDENCIES - EMAIL_EXTERNAL_ABSENT_STAKEHOLDER_MENTIONS - EMAIL_EXTERNAL_FRUSTRATION_OR_DISAPPOINTMENT - EMAIL_OVERALL_SENTIMENT - EMAIL_TITLE_TO_PERSONA - EMAIL_SEGMENT_DESCRIPTION - SOCIAL_INTERNAL_USE_CASE - SOCIAL_INTERNAL_PROOF_POINT - SOCIAL_INTERNAL_PAIN_POINT - SOCIAL_INTERNAL_VALUE_PROP - SOCIAL_INTERNAL_SOCIAL_PROOF - SOCIAL_INTERNAL_CALL_TO_ACTION - SOCIAL_INTERNAL_BENEFITS_HIGHLIGHTED - SOCIAL_INTERNAL_OBJECTION_HANDLING - SOCIAL_TITLE_TO_PERSONA - SOCIAL_SEGMENT_DESCRIPTION - SOCIAL_EXTERNAL_CALL_TO_ACTION - SOCIAL_EXTERNAL_OBJECTION - SOCIAL_EXTERNAL_QUESTION - SOCIAL_EXTERNAL_INTEREST_EXPRESSION - SOCIAL_EXTERNAL_FEATURE_REQUEST - SOCIAL_EXTERNAL_REQUIREMENT - SOCIAL_EXTERNAL_PRICING_FEEDBACK - SOCIAL_EXTERNAL_COMPARATIVE_STATEMENT - SOCIAL_EXTERNAL_KEY_TAKEAWAY - SOCIAL_EXTERNAL_COMPETITOR_MENTION - SOCIAL_EXTERNAL_NEXT_STEP - SOCIAL_EXTERNAL_URGENCY_INDICATOR - SOCIAL_EXTERNAL_DECISION_MAKING_SIGNAL - SOCIAL_EXTERNAL_UNIQUE_LANGUAGE_USED - SOCIAL_OVERALL_SENTIMENT - CALL_EXTERNAL_BUSINESS_PROBLEMS - CALL_EXTERNAL_IDEAL_SOLUTION_DESCRIPTION - CALL_EXTERNAL_PRIMARY_GOALS - CALL_EXTERNAL_WHY_ON_THIS_CALL - CALL_EXTERNAL_STATUS_QUO_HOW_THEY_SOLVE_TODAY - CALL_EXTERNAL_INDUSTRY_TRENDS - CALL_EXTERNAL_COMPETITORS_TO_OUR_OFFERING - CALL_EXTERNAL_COMPETITORS_OF_THEIR_COMPANY - CALL_EXTERNAL_CURRENT_TOOL_OR_SOLUTION_PROBLEMS - CALL_EXTERNAL_OBJECTIONS - CALL_EXTERNAL_PAIN_OR_PROBLEM_AGREEMENTS - CALL_EXTERNAL_ROLE_OR_RESPONSIBILITIES_DESCRIPTION - CALL_EXTERNAL_QUESTIONS_OR_CONFUSION_ABOUT_OFFERING - CALL_EXTERNAL_CAPABILITIES_THAT_DREW_EXCITEMENT - CALL_EXTERNAL_UNIQUE_LANGUAGE_USED - CALL_EXTERNAL_FEATURE_REQUEST - CALL_EXTERNAL_COMMITMENTS_MADE - CALL_EXTERNAL_PRICING_OR_PACKAGING_FEEDBACK - CALL_EXTERNAL_BLOCKERS_OR_DEPENDENCIES - CALL_EXTERNAL_ABSENT_STAKEHOLDER_MENTIONS - CALL_EXTERNAL_FRUSTRATION_OR_DISAPPOINTMENT - CALL_EXTERNAL_CORE_CAPABILITIES - CALL_EXTERNAL_USE_CASES_BROUGHT_UP - CALL_INTERNAL_USE_CASES_BROUGHT_UP - CALL_INTERNAL_PROOF_POINTS - CALL_INTERNAL_REFERENCE_CUSTOMERS_OR_SOCIAL_PROOF - CALL_INTERNAL_COMPETITORS - CALL_INTERNAL_COMPETITORS_TO_OUR_OFFERING - CALL_INTERNAL_OBJECTION_HANDLING - CALL_INTERNAL_VALUE_PROP_PRESENTATIONS - CALL_INTERNAL_DIFFERENTIATED_VALUE - CALL_INTERNAL_CORE_CAPABILITIES - CALL_INTERNAL_COMPLEMENTARY_TOOLS_MENTIONED - CALL_INTERNAL_COMMITMENTS_MADE - CALL_COMPETITOR_MENTION_ORIGIN - CALL_COMPETITOR_RELATIONSHIP_STATUS - CALL_COMPETITOR_MENTAL_MODEL - CALL_COMPETITOR_PROSPECT_VOICED_STRENGTH - CALL_COMPETITOR_PROSPECT_VOICED_WEAKNESS - CALL_COMPETITOR_OVERALL_STANCE - CALL_COMPETITOR_HEAD_TO_HEAD_COMPARISON - CALL_COMPETITOR_CONSIDERATION_SET_ALTERNATIVE - CALL_COMPETITOR_COMMERCIAL_INTEL - CALL_COMPETITOR_SWITCHING_TRIGGER_OR_BARRIER - CALL_COMPETITOR_REP_CLAIM_REACTION - CALL_COMPETITOR_DEAL_IMPACT - CALL_CORE_FEATURE_MENTION_ORIGIN - CALL_CORE_FEATURE_PROSPECT_LANGUAGE - CALL_CORE_FEATURE_COMPREHENSION_CORRECTION - CALL_CORE_FEATURE_PROSPECT_REACTION - CALL_CORE_FEATURE_PROSPECT_QUESTION - CALL_CORE_FEATURE_PROBLEM_ATTACHMENT - CALL_CORE_FEATURE_VALUE_ARTICULATION - CALL_CORE_FEATURE_CONCERN_OR_REQUIREMENT - CALL_CORE_FEATURE_STATUS_QUO - CALL_CORE_FEATURE_COMPARISON - CALL_CORE_FEATURE_DECISION_WEIGHT - CALL_CORE_FEATURE_USAGE_STAKEHOLDER - CALL_OBJECTION_UNDERLYING_CONCERN - CALL_OBJECTION_ASSUMPTION_OR_MISCONCEPTION - CALL_OBJECTION_SEVERITY - CALL_OBJECTION_STANCE - CALL_OBJECTION_UNPROBED_GAP - CALL_OBJECTION_REP_RESPONSE - CALL_OBJECTION_PROOF_DEMANDED - CALL_OBJECTION_RESOLUTION_STATE - CALL_ALTERNATIVE_APPROACH_STANCE - CALL_ALTERNATIVE_INCUMBENCY_STATE - CALL_ALTERNATIVE_BUILD_AND_MAINTENANCE - CALL_ALTERNATIVE_RATIONAL_CASE - CALL_ALTERNATIVE_PERCEIVED_BENEFIT - CALL_ALTERNATIVE_VOICED_LIMITATION - CALL_ALTERNATIVE_SWITCHING_BARRIER - CALL_ALTERNATIVE_DISPLACEMENT_TRIGGER - CALL_ALTERNATIVE_DEFENDER - CALL_ALTERNATIVE_REP_POSITIONING - CALL_ALTERNATIVE_STANDING - RESOURCE_USE_CASES - RESOURCE_PROOF_POINTS - RESOURCE_REFERENCE_CUSTOMERS - RESOURCE_COMPETITORS - RESOURCE_OBJECTION_HANDLING - RESOURCE_VALUE_PROPS - RESOURCE_DIFFERENTIATED_VALUE - RESOURCE_CORE_CAPABILITIES - RESOURCE_SEGMENTS - RESOURCE_INTEGRATIONS_PARTNERS - RESOURCE_UNIQUE_LANGUAGE - RESOURCE_PAIN_POINTS - RESOURCE_TARGET_PERSONAS - RESOURCE_ALTERNATIVES - RESOURCE_BUYING_TRIGGERS - DECLARED_ENTITY_USE_CASES - DECLARED_ENTITY_COMPETITORS - DECLARED_ENTITY_PROOF_POINTS - CALL_OVERALL_SENTIMENT - CALL_PURPOSE_CLASSIFICATION - CALL_TITLE_TO_PERSONA - CALL_SEGMENT_DESCRIPTION - CRM_TITLE_TO_PERSONA - CRM_SEGMENT_DESCRIPTION - EVENT_SUMMARY - BULK_IMPORT_THEMES - BULK_LOSS_REASONS - BULK_WIN_REASONS - BULK_PAIN_POINTS - BULK_USE_CASES - BULK_COMPETITORS - BULK_OBJECTIONS - BULK_SEGMENTS - BULK_PERSONAS - ADS_INTERNAL_MESSAGING_THEME - ADS_INTERNAL_TARGET_AUDIENCE - ADS_INTERNAL_COMPETITIVE_POSITIONING - ADS_INTERNAL_KEYWORD_TARGETING - ADS_EXTERNAL_ENGAGEMENT_SIGNAL - ADS_SEGMENT_DESCRIPTION - ADS_MOTION_TYPE - ADS_OFFERING_MATCH - CALL_PROSPECT_RELATIONSHIP_TO_SELLER - CALL_MOTION_TYPE - CALL_OFFERING_MATCH - EMAIL_PROSPECT_RELATIONSHIP_TO_SELLER - EMAIL_REPLY_PURPOSE_CLASSIFICATION - EMAIL_MOTION_TYPE - EMAIL_OFFERING_MATCH - CRM_MOTION_TYPE - CRM_OFFERING_MATCH - RESOURCE_OFFERING_MATCH - RESOURCE_TYPE_CLASSIFICATION - CUSTOM customExtractor: type: object nullable: true properties: oId: type: string name: type: string nullable: true promptVersion: type: integer nullable: true minimum: 0 modelTier: type: string nullable: true enum: - NOTE - PULSE - ECHO - HARMONY - CHORUS - SYMPHONY - null model: type: string nullable: true required: - oId - name - promptVersion - modelTier - model description: >- For CUSTOM findings: the workspace-defined custom extractor that produced this finding. Name and promptVersion are extraction-time snapshots. Null for built-in extraction types. structuredValue: type: object nullable: true additionalProperties: nullable: true description: >- Schema-validated fields for OBJECT-mode custom findings. Null for other finding shapes. eventOId: type: string eventType: 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 eventTimestamp: type: string nullable: true format: date-time callPurpose: type: string nullable: true enum: - DISCOVERY - DEMO - TECHNICAL_EVALUATION - WORKING_SESSION - NEGOTIATION_PRICING - ONBOARDING - CHECK_IN_SUCCESS - QBR_RENEWAL - EXPANSION_UPSELL - ESCALATION_CHURN_RISK - SUPPORT - INTERNAL_SYNC - OTHER - null description: >- Classified purpose of the finding's call. Null for non-call findings, for calls ingested before purpose classification stamped them, and for a stamped value no longer in the enum. company: type: object nullable: true properties: name: type: string nullable: true domain: type: string nullable: true required: - name - domain evidence: type: object nullable: true properties: quote: type: string nullable: true reasoning: type: string nullable: true speakerLabel: type: string nullable: true required: - quote - reasoning - speakerLabel description: >- Compact evidence retained with the persisted finding: verbatim quote, extractor rationale/response summary, and the extractor-reported transcript speaker label when present. speakerLabel is evidence text, not an authoritative participant identity; use attributedParticipant for resolved identity and /event/get for the full event. sentimentScore: type: number nullable: true description: >- Signed emotional valence of the speaker in this moment, on a -2..+2 scale (-2 strongly negative, 0 neutral, +2 strongly positive). Stamped at extraction time, primarily on buyer-side call findings; null when not scored. Moment-level sentiment — the call-level anchor is the event's overall sentiment. speaker: type: string nullable: true enum: - internal - external - null description: >- Which side of the conversation the finding's speaker was on: internal (the workspace's own team) or external (prospect/customer side). Null for findings with no conversation side, e.g. RESOURCE_* document findings. attributedParticipant: type: object nullable: true properties: participantOId: type: string contactOId: type: string nullable: true name: type: string nullable: true email: type: string nullable: true confidence: type: string nullable: true personaOId: type: string nullable: true personaName: type: string nullable: true required: - participantOId - contactOId - name - email - confidence - personaOId - personaName description: >- The specific person this finding was attributed to (rep on the internal side, stakeholder on the external side), including the persona that contact is classified into when known. Null when the speaker couldn't be resolved. linkedEntities: type: object properties: personas: type: array items: type: string competitors: type: array items: type: string playbooks: type: array items: type: string segments: type: array items: type: string useCases: type: array items: type: string references: type: array items: type: string proofPoints: type: array items: type: string coreFeatures: type: array items: type: string alternatives: type: array items: type: string buyingTriggers: type: array items: type: string description: Library entity oIds this finding is tagged with required: - oId - snippetText - extractionType - structuredValue - eventOId - eventType - eventTimestamp - callPurpose - company - evidence - speaker - attributedParticipant securitySchemes: ApiKeyAuth: type: apiKey in: header name: api_key ````