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

# What are Custom Extractors in Octave?

> Custom Extractors are workspace-defined finding types: your own prompt, run over the events you choose, producing findings that flow through the same pipeline as Octave's built-in extraction.

## What is a Custom Extractor?

Octave's [analytics pipeline](/concepts/analytics) extracts a fixed set of finding types from every event: objections, pain points, competitor mentions, use cases, and the rest. A Custom Extractor adds your own. You describe what to look for in plain language, pick which events it runs on, and Octave produces findings for it alongside the built-in ones.

Use one when the question is specific to your business: which calls mention a security review, how many prospects bring up a particular integration, what budget range buyers state on discovery calls, whether the rep ran the qualification framework your team uses.

Custom Extractors require the custom-extractors entitlement.

## What an extractor defines

| Field | Purpose |
| - | - |
| Prompt | What to look for, in plain language |
| Event types | Which events it runs on, such as `CALL_TRANSCRIPT`, `EMAIL_REPLY_RECEIVED`, or `DEAL_LOST` |
| Event filters | Optional `match` / `exclude` filters that narrow the events further: deal stage, deal motion, call purpose, linked Library entities, and more |
| Perspective | Whose words to mine: `EXTERNAL` (the prospect, the default), `INTERNAL` (your team), or `ANY` |
| Output mode | The shape of each finding (see below) |
| Model tier | How capable (and how expensive) a model runs it |
| Field targets | Optional Library entity fields the findings are attached to as evidence |

### Output modes

| Mode | What each finding holds |
| - | - |
| `freeform` | A quoted snippet and reasoning, like a built-in finding |
| `boolean` | A yes/no verdict for the event |
| `number` | A number, with a unit and optional bounds |
| `enum_single` / `enum_multi` | One or several choices from classes you define |
| `object` | A record validated against a JSON Schema you provide, either one per event or one per occurrence |

When you create an extractor, Octave runs a one-time mapping that proposes which [Library](/concepts/library) entities its findings relate to. You can adjust those anchors afterwards.

## Lifecycle

An extractor is created `ACTIVE` by default, which means it runs on every newly ingested event that matches. Create it as `DRAFT` to hold it for review and backtesting first. `PAUSED` stops it temporarily, and `ARCHIVED` stops it for good while keeping its findings. Deleting an extractor also retires every finding it produced, along with any Insight that reports on that extractor alone.

## Test, then run on history

A new extractor only sees events that arrive after it is active. The recommended path to cover history:

1. **Backtest.** Run the saved extractor, or an unsaved draft, against up to 10 real events without saving any findings. Use it to tune the prompt.
2. **Estimate.** Count the historical events the extractor would select in a time window and estimate the credits.
3. **Backfill.** Start a durable background job over that window. It saves progress, resumes after interruptions, skips events that already have findings from this extractor, and can be paused, resumed, or cancelled.
4. **Purge if needed.** If a backfill ran with the wrong criteria, purge the extractor's findings, fix the definition, and backfill again.

Every event an extractor processes, in a backtest or a backfill, is a credit-charged LLM call.

## Reading the results

Custom findings are ordinary findings. Search them with [Search Findings](/v2-api-reference/findings/search-findings), filtering by `customExtractorOIds`, and aggregate them with the [event analytics](/concepts/analytics#event-analytics) endpoints.

## Managing Custom Extractors via API

* `GET /api/v2/custom-extractor/list`: list extractors with their full definitions
* `POST /api/v2/custom-extractor/create`: create an extractor
* `POST /api/v2/custom-extractor/update`: change its definition, anchors, or status
* `DELETE /api/v2/custom-extractor/delete`: delete it and retire its findings
* `POST /api/v2/custom-extractor/backtest`: try it on up to 10 events without saving findings
* `POST /api/v2/custom-extractor/backfill/estimate`: count events and estimate credits for a backfill
* `POST /api/v2/custom-extractor/backfill/start`: start a historical backfill
* `GET /api/v2/custom-extractor/backfill/get`: check a backfill's progress
* `POST /api/v2/custom-extractor/backfill/control`: pause, resume, or cancel a backfill
* `POST /api/v2/custom-extractor/purge-findings`: retire its findings but keep the extractor