> ## 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.

# How does Octave learn from your conversations?

> Octave analyzes every sales call, email, and deal outcome to surface insights, reports, and findings that keep your GTM strategy in sync with reality.

## A self-improving GTM system

Most GTM knowledge lives in static documents that drift from reality within weeks. Octave closes that gap by continuously ingesting your real customer interactions, extracting structured signal, and feeding it back into the [Library](/concepts/library) — creating a loop where your strategy informs your agents, your agents drive conversations, and those conversations refine your strategy.

The pipeline is built on four layers:

1. **Events** — the raw stream of things that happened (emails sent, calls held, deals won, opportunities created).
2. **Findings** — structured extractions from those events (a pain point mentioned, an objection raised, a competitor cited).
3. **Insights** — aggregated metrics across findings (win-rate lift per entity, library health, competitive landscape).
4. **Reports** — narrative analyses synthesizing findings and insights on a schedule or trigger.

Each layer is independently addressable via the API and the dashboard.

## Events

Every customer touchpoint Octave processes becomes an Event in your workspace timeline. Event categories include `EMAIL`, `CALL`, `CRM`, `SOCIAL`, `ADS`, `RESOURCE`, and `REVISION`. Common event types include:

* `EMAIL_SENT`, `EMAIL_REPLY_RECEIVED`
* `CALL_TRANSCRIPT`
* `DEAL_WON`, `DEAL_LOST`, `OPPORTUNITY_CREATED`, `MEETING_BOOKED`
* `SOCIAL_MESSAGE_SENT`, `SOCIAL_MESSAGE_RECEIVED`, `SOCIAL_CONNECTION_SENT`
* `RESOURCE_INDEXED`, `RESOURCE_REINDEXED`
* `ENTITY_CREATED`, `ENTITY_UPDATED`

Events are queryable through `GET /api/v2/event/list` and can be filtered by category, type, and time range.

## Findings

A Finding is a structured extraction from an event — a specific signal Octave detected, tagged with a type and linked to the [Library](/concepts/library) entity it relates to. Findings are the atoms of conversation intelligence.

| Source           | Example finding types                                                                                                                                                                                                                           |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Email (internal) | use case, proof point, pain point, value prop, call to action, objection handling                                                                                                                                                               |
| Email (external) | objection, question, interest expression, feature request, requirement, pricing feedback, competitor mention, urgency indicator, decision-making signal                                                                                         |
| Call             | pain points, [competitors](/concepts/competitors) discussed, [use cases](/concepts/use-cases) referenced, [proof points](/concepts/proof-points) cited, [buying triggers](/concepts/buying-triggers), [objections](/concepts/objections) raised |
| Social           | interest expression, key takeaway, objection, sentiment                                                                                                                                                                                         |
| Deal outcomes    | which [motions](/concepts/motions) appear in won deals, which [segments](/concepts/segments) close fastest, where you win and lose                                                                                                              |

Findings are queryable through `GET /api/v2/finding/list` and can be filtered by type and time range.

## Insights

Insights aggregate findings into the metrics that drive day-to-day GTM decisions. The Insights API surfaces six views, each scoped to a period (`week`, `month`, or `quarter`):

| Endpoint                                  | What it returns                                                                                                                                                                                                                                    |
| ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /api/v2/insights/top-entities`       | Highest-lift (or lowest-lift) Library entities for the period, across any combination of entity types — persona, product, service, solution, use case, motion, proof point, competitor, alternative, buying trigger, objection, reference, segment |
| `GET /api/v2/insights/entity-stats`       | Per-entity finding counts and deal impact                                                                                                                                                                                                          |
| `GET /api/v2/insights/entity-time-series` | A specific entity's metrics over time                                                                                                                                                                                                              |
| `GET /api/v2/insights/competitive`        | Competitor and alternative landscape, sorted by win-rate impact                                                                                                                                                                                    |
| `GET /api/v2/insights/library-health`     | Per-entity-type health summary — findings volume, deal counts, coverage gaps                                                                                                                                                                       |
| `GET /api/v2/insights/workspace-baseline` | Workspace-wide baseline metrics for the period                                                                                                                                                                                                     |

These power the dashboard charts directly and are designed to be embedded in your own BI tools.

## Reports

Reports turn findings into narrative analyses on a schedule or in response to a trigger. The reporting system has three layers:

* **Report Group** — a recurring schedule or push-triggered analysis (`scheduled` or `push`, aggregating `day` / `week` / `month`).
* **Report Config** — one analysis within a group: the prompt, system prompt, logic version, and the filter selecting which events and findings flow in.
* **Report Run** — an individual execution producing a titled, summarized report with ordered sections and an optional comparison against the previous run.

Each Report Run returns AI-generated title and summary text plus an array of Report Sections — topic, narrative details, and the count of supporting findings each section is grounded in. Report Groups can be triggered on schedule, on cluster creation, on outcome creation, or when specific event types are processed.

API surface:

* `GET /api/v2/report-group/list` and `GET /api/v2/report-group/get` — manage and inspect report groups
* `GET /api/v2/report-config/list` and `GET /api/v2/report-config/get` — manage individual report configs
* `GET /api/v2/report-run/list` and `GET /api/v2/report-run/get` — list and read report runs and their sections

## How findings feed back into the Library

When Octave detects a recurring pattern in findings — a new objection appearing across multiple calls, a [competitor](/concepts/competitors) gaining mention frequency, a value prop landing in won deals — it generates a suggestion to update the [Library](/concepts/library). Suggestions can propose creating a new entity (a new [Objection](/concepts/objections), [Competitor](/concepts/competitors), or [Buying Trigger](/concepts/buying-triggers)) or refining an existing one (adding a newly discovered pain point to a [Persona](/concepts/personas), updating a Motion ICP narrative, attaching a new proof point).

[Motion ICPs](/concepts/motions#motion-icps) consume these findings directly as learnings — `KEY_LANGUAGE`, `INDUSTRY_TREND`, `PAIN_POINT`, `VALUE_PROP`, `OBJECTION` — each carrying a confidence score and evidence count.

Your team reviews and accepts suggestions from the dashboard. Accepted suggestions update the Library, which immediately changes what every agent and workflow sees on the next run.

## The result

Every conversation makes your system smarter. A call where a prospect raises a new objection today becomes a structured [Objection](/concepts/objections) entity tomorrow, attached to the right Motion ICP, and pre-handled in every relevant outbound email going forward. A lost deal against a new competitor becomes a competitive Motion Playbook within days, not quarters.