For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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

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. The names in the table above are not accepted here.

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.

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

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.

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

Last updated