> For the complete documentation index, see [llms.txt](https://docs.heron-intelligence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.heron-intelligence.com/documentation/data-providers.md).

# Data Providers

The four research datasets behind Heron Intelligence — what each one is, who conducts it, and how to reference it in API and MCP requests.

Every transcript Heron Intelligence returns carries a `data_provider_name` identifying which of our research datasets produced it. This page is the canonical definition of those datasets. The REST API and the MCP server both draw on the same four.

## The four datasets

| `data_provider_name` | Conducted by           | Diligence type | In one line                                                     |
| -------------------- | ---------------------- | -------------- | --------------------------------------------------------------- |
| `Blue Heron`         | Human — researcher-led | MDD and BDD    | Our deepest, most rigorously sourced diligence.                 |
| `Paragon`            | Human                  | MDD only       | Management diligence at scale across public-company leadership. |
| `Heron AI`           | AI interviewer         | BDD            | Broader, more recent business diligence.                        |
| `Heron AI Events`    | AI interviewer         | BDD            | Event-driven diligence, delivered in 48–72 hours.               |

See [Data Models](/documentation/data-models.md) for what MDD and BDD mean.

### Blue Heron

Researcher-led diligence interviews conducted by former investigative journalists with senior operators, former employees, customers and competitors. Blue Heron covers both Management Due Diligence (MDD) and Business Due Diligence (BDD), and is the most thoroughly sourced of the four datasets.

When naming this source to an end user, use its full name — **Blue Heron Researcher-lead Diligence** — rather than "Blue Heron" alone.

### Paragon

Human-conducted Management Due Diligence, focused on public-company leadership teams with broad coverage across large-cap names. Paragon is a Heron Intelligence company and its interviews are conducted by people, not by an AI interviewer.

Paragon produces **MDD only**. A Paragon result will never carry `due_diligence_type: "BDD"`.

{% hint style="warning" %}
`list_data_providers` still reports `produced_by: "third_party"` for Paragon, along with a description calling it a licensed third-party feed. That metadata predates the acquisition and is wrong. See [Known issues in server-generated provenance text](#known-issues-in-server-generated-provenance-text).
{% endhint %}

### Heron AI

Business Due Diligence interviews conducted by an AI interviewer rather than a human researcher. Coverage is broader and often more recent than the human-led set. Report these under the name `Heron AI` — see [Reporting provenance to end users](#reporting-provenance-to-end-users) — and never imply they are less reliable.

### Heron AI Events

Event-driven diligence: AI-conducted interviews with industry experts, completed and delivered within **48 to 72 hours** of a market-moving event.

The dataset is defined by that turnaround, not by any single event type. Production today is concentrated on earnings as the triggering event — the subset commonly referred to as **earnings diligence** — and will broaden to other event types over time.

{% hint style="warning" %}
`Heron AI Events` and `Heron AI` are two different datasets whose names differ by one word. They are never interchangeable. `Heron AI Events` is event-triggered and time-boxed; `Heron AI` is standing business diligence. Passing one where you meant the other returns a valid response containing the wrong dataset — with no error to warn you.
{% endhint %}

`Heron AI Events` contains expert interviews about a company around the time of an event. It does **not** contain the event's own earnings call, and Heron Intelligence does not distribute earnings call recordings or transcripts through any API surface.

## Referencing a provider in a request

The two surfaces identify a provider **differently**. The REST API filters by provider **id**; the MCP server filters by provider **name**.

| Surface                                                                                 | Parameter                  | Value                                           |
| --------------------------------------------------------------------------------------- | -------------------------- | ----------------------------------------------- |
| REST `GET /api/v1/interviews` (and `/transcripts`)                                      | `data_source_provider_ids` | Comma-separated provider **UUIDs**              |
| MCP `get_recent_transcripts`, `search_people`, drop `content_filters.interview_sources` | `data_provider_names`      | The exact **name** strings from the table above |

### REST — filter by id

`data_source_provider_ids` takes a comma-separated list of the provider UUIDs returned by [`GET /api/v1/data-sources`](/api-reference/api-reference/data-sources.md). The names in the table above are **not** accepted here.

```bash
curl -s "https://api.heron-intelligence.com/api/v1/interviews?data_source_provider_ids=<ID_1>,<ID_2>" \
  -H "x-api-key: $HERON_API_KEY"
```

Resolve the ids once from `GET /api/v1/data-sources` and cache them — they are stable. Each interview echoes the provider it came from in `data_source_provider` (`{ id, name }`), so you can map results back to a name without a second lookup. A value that is not a well-formed UUID returns `422`.

### MCP — filter by name

* **Pass the string verbatim.** Matching is case-insensitive; spelling is not. `Heron Events`, `Heron AI events` and `heron-ai-events` are not accepted values — only `Heron AI Events` is.
* **Pass several at once** rather than issuing one call per provider: `data_provider_names=["Blue Heron", "Paragon"]`.
* **An unrecognized name returns `422`**, and the error body carries the list of valid names. Read that list and retry with a name from it. A `422` here means you misspelled a provider — it never means the company has no coverage.
* Call `list_data_providers` rather than guessing a name.

## Access depends on your subscription

All four datasets exist, but the ones you can read are determined by your subscription. Your entitlements are configured per API key.

{% hint style="danger" %}
Filtering by a valid provider your subscription does not include returns an **empty result set, not an error**. An empty response after filtering by provider may mean "not entitled" rather than "no coverage exists" — do not report it to an end user as an absence of research.
{% endhint %}

To tell the two cases apart, check what you are entitled to first:

| Question                                  | Where to look                                                                                                                                                            |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Which providers can *I* read?             | REST [`GET /api/v1/data-sources`](/api-reference/api-reference/data-sources.md) — scoped to your API key's entitlements, and the source of the ids REST filtering needs. |
| Which provider names are *valid to send*? | MCP `list_data_providers` — the full catalog, independent of entitlement. See [MCP Server](/overview/mcp.md).                                                            |

If a provider you expect is missing from `GET /api/v1/data-sources`, your key is not entitled to it. Contact the Heron Intelligence team to change your subscription.

## Reporting provenance to end users

Transcript list responses carry the per-transcript `data_provider_name` plus, on the MCP surface, an aggregate `provenance` object keyed by that same name.

**Build every count from `provenance`.** It is the durable contract: one key per dataset, with the count for the set returned.

* **Name the dataset.** `Heron AI Events`, not "AI-conducted". The dataset name *is* the attribution, and it is the only label guaranteed to match the data.
* **Never merge two datasets into one figure.** `Heron AI` and `Heron AI Events` are counted separately and must be reported separately.
* **Never introduce a label that is not a key in `provenance`.**
* **Say what the counts cover.** On `get_recent_transcripts` the `provenance` counts describe the **page returned**, not the scope. When `capped` is `true`, state both the returned count and `total_in_window`. For coverage totals use `get_company_overview` / `get_companies_overview` — see [Which count is authoritative](/overview/mcp.md#which-count-is-authoritative).

If asked how the research was produced, answer accurately from the table at the top of this page. Never imply an AI-conducted interview was human-led, or the reverse.

### Known issues in server-generated provenance text

{% hint style="danger" %}
Two server-side fields currently misreport provenance. Both are being fixed; until then, **do not pass either through to an end user verbatim**.

* **`provenance_note`** on transcript-list responses is a pre-rendered English sentence. It merges `Heron AI Events` into `Heron AI`, labels `Paragon` as a "third-party provider", and states page-scoped counts without disclosing that they are page-scoped. Derive your own sentence from the `provenance` dict instead.
* **`produced_by` and `description`** on `list_data_providers` still carry pre-acquisition metadata for `Paragon` (`produced_by: "third_party"`, and a description calling it a licensed third-party feed). Paragon is a Heron Intelligence company producing human-conducted MDD. Use `name` from that tool; take the rest from this page.
  {% endhint %}