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.
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 eventsandheron-ai-eventsare not accepted values — onlyHeron AI Eventsis.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. A422here means you misspelled a provider — it never means the company has no coverage.Call
list_data_providersrather 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:
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 AIandHeron AI Eventsare 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_transcriptstheprovenancecounts describe the page returned, not the scope. Whencappedistrue, state both the returned count andtotal_in_window. For coverage totals useget_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