Interviews

Retrieve interview transcripts and related data for specific companies.

/api/v1/transcripts is an alias for /api/v1/interviews — same parameters, same response. Either path works; pick one and stay with it.

Filters

All filters are optional and compose. Unless noted, an unmatched value returns an empty page rather than an error.

Parameter	Type	Notes
id	UUID	A single transcript id.
ids	string	Several transcript ids, comma-separated.
company_id	UUID	Resolve it first with GET /companies.
company_name	string	Partial, case-insensitive match on an associated company.
company_ticker	string	Exact ticker of an associated company.
data_source_provider_ids	string	Provider UUIDs, comma-separated. Ids come from GET /data-sources — provider names are not accepted here.
due_diligence_type	string	BDD or MDD. See Data Models.
transcript_type	enum	conversation or monologue.
project_affiliation	string	Search by the research project the interview belongs to.
call_date_min / call_date_max	date-time	Inclusive bounds on the interview date.
length_min / length_max	integer	Transcript length in characters.
ordering	string	Field name, - prefix for descending — e.g. -call_date, post_date, project_affiliation.
page / per_page	integer	page starts at 1; per_page defaults to 20, max 100.

due_diligence_type is the filter for MDD/BDD. The call_type field in the response is free text and is not the same thing — do not filter on the value you see there.

Response fields

Results arrive in the standard paginated envelope (data, pagination) described in Data Models. Each item contains:

Field	Notes
transcript_id	UUID. Resolvable via GET /interviews/{transcript_id}.
companies[]	Companies discussed — company_id, company_name, stock_ticker, exchange, isin.
people[]	Interviewees — person_id, full_name, title, bio. See People.
call_date / post_date	When the interview was conducted and published. Either may be null.
project_affiliation	The research project the interview was delivered against.
research_id	The project's public id, when the interview came from a research request. Resolvable via GET /operations/research-request/{research_id}.
transcript_type	conversation or monologue.
call_type	Free-text call descriptor. Nullable.
length	Transcript length in characters.
transcript[]	The interview itself, as { question, answer } pairs.
transcript_summary	Pre-written summary of the interview, when available.
data_source_provider	{ id, name } — which dataset produced this interview. See Data Providers.
metadata	call_quality, call_tone, and a compliance_paragraph carrying the required disclosures.
url	Link to the interview. Always present.

The full transcript ships inline on every list item, so a wide per_page returns a large payload. Narrow with filters rather than paging through everything.

When you summarize across interviews, report the source breakdown from data_source_provider.name and never merge two datasets into one figure — Heron AI and Heron AI Events in particular are different datasets. See Reporting provenance to end users.

List Interviews

Get Interviews

get

Get interviews with filtering, rich content, and pagination.

Returns paginated interviews with:

• Companies associated with the interview (including ISIN if available)
• People involved in the interview
• Transcript ID and metadata (call date, post date, call type, etc.)
• Complete transcript content as question/answer pairs
• Metadata object with call quality and call tone
• Pagination metadata

Query parameters

idstring · uuid · nullableOptional

Filter by transcript ID

idsstring · nullableOptional

Filter by multiple transcript IDs (comma-separated, e.g., 'id1,id2,id3')

data_source_provider_idsstring · nullableOptional

Filter by data source provider IDs (comma-separated, e.g., 'id1,id2,id3')

project_affiliationstring · nullableOptional

Search by transcript project affiliation

transcript_typestring · enum · nullableOptional

Filter by transcript type

Possible values:

due_diligence_typestring · nullableOptional

Filter by due diligence type (BDD or MDD)

call_date_minstring · date-time · nullableOptional

Filter by minimum call date

call_date_maxstring · date-time · nullableOptional

Filter by maximum call date

length_mininteger · nullableOptional

Filter by minimum transcript length in characters

length_maxinteger · nullableOptional

Filter by maximum transcript length in characters

company_idstring · uuid · nullableOptional

Filter by associated company ID

company_namestring · nullableOptional

Search by associated company name

company_tickerstring · nullableOptional

Filter by associated company ticker

orderingstring · nullableOptional

Order results by field. Use '-' prefix for descending (e.g., 'project_affiliation', '-call_date', 'post_date', '-post_date')

pageinteger · min: 1Optional

Page number (starts from 1)

Default: 1

per_pageinteger · min: 1 · max: 100Optional

Number of items per page (max 100)

Default: 20

Header parameters

x-api-keystring · nullableOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get/api/v1/interviews

GET /api/v1/interviews HTTP/1.1
Accept: */*

{
  "data": [
    {
      "companies": [
        {
          "company_id": "123e4567-e89b-12d3-a456-426614174000",
          "company_name": "text",
          "stock_ticker": "text",
          "exchange": "text",
          "isin": "text"
        }
      ],
      "people": [
        {
          "person_id": "123e4567-e89b-12d3-a456-426614174000",
          "full_name": "text",
          "title": "text",
          "bio": "text"
        }
      ],
      "transcript_id": "123e4567-e89b-12d3-a456-426614174000",
      "call_date": "2026-01-01",
      "post_date": "2026-01-01",
      "project_affiliation": "text",
      "transcript_type": "conversation",
      "call_type": "text",
      "length": 1,
      "research_id": "123e4567-e89b-12d3-a456-426614174000",
      "transcript": [
        {
          "question": "text",
          "answer": "text"
        }
      ],
      "url": "text",
      "metadata": {
        "call_quality": "text",
        "call_tone": "text",
        "compliance_paragraph": "text"
      },
      "data_source_provider": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text"
      },
      "transcript_summary": "text"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 1,
    "total_items": 1,
    "total_pages": 1,
    "has_next": true,
    "has_previous": true,
    "next_page": 1,
    "previous_page": 1
  }
}

Get Interview by ID

Get Interview By Id

get

Get a specific interview by transcript ID.

Returns complete interview information including:

• Companies associated with the interview (including ISIN if available)
• People involved in the interview
• Transcript metadata (call date, post date, call type, etc.)
• Complete transcript content as question/answer pairs
• Metadata object with call quality and call tone

Path parameters

transcript_idstringRequired

Header parameters

x-api-keystring · nullableOptional

Responses

200

Successful Response

application/json

Interview response matching the desired API schema

transcript_idstring · uuidRequired

call_datestring · date · nullableRequired

post_datestring · date · nullableRequired

project_affiliationstringRequired

transcript_typestring · enum · nullableRequiredPossible values:

call_typestring · nullableRequired

lengthinteger · nullableRequired

research_idstring · uuid · nullableRequired

urlstringRequired

transcript_summarystring · nullableOptional

422

Validation Error

application/json

get/api/v1/interviews/{transcript_id}

GET /api/v1/interviews/{transcript_id} HTTP/1.1
Accept: */*

{
  "companies": [
    {
      "company_id": "123e4567-e89b-12d3-a456-426614174000",
      "company_name": "text",
      "stock_ticker": "text",
      "exchange": "text",
      "isin": "text"
    }
  ],
  "people": [
    {
      "person_id": "123e4567-e89b-12d3-a456-426614174000",
      "full_name": "text",
      "title": "text",
      "bio": "text"
    }
  ],
  "transcript_id": "123e4567-e89b-12d3-a456-426614174000",
  "call_date": "2026-01-01",
  "post_date": "2026-01-01",
  "project_affiliation": "text",
  "transcript_type": "conversation",
  "call_type": "text",
  "length": 1,
  "research_id": "123e4567-e89b-12d3-a456-426614174000",
  "transcript": [
    {
      "question": "text",
      "answer": "text"
    }
  ],
  "url": "text",
  "metadata": {
    "call_quality": "text",
    "call_tone": "text",
    "compliance_paragraph": "text"
  },
  "data_source_provider": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text"
  },
  "transcript_summary": "text"
}

Aliases

Get Interviews

get

Get interviews with filtering, rich content, and pagination.

Returns paginated interviews with:

• Companies associated with the interview (including ISIN if available)
• People involved in the interview
• Transcript ID and metadata (call date, post date, call type, etc.)
• Complete transcript content as question/answer pairs
• Metadata object with call quality and call tone
• Pagination metadata

Query parameters

idstring · uuid · nullableOptional

Filter by transcript ID

idsstring · nullableOptional

Filter by multiple transcript IDs (comma-separated, e.g., 'id1,id2,id3')

data_source_provider_idsstring · nullableOptional

Filter by data source provider IDs (comma-separated, e.g., 'id1,id2,id3')

project_affiliationstring · nullableOptional

Search by transcript project affiliation

transcript_typestring · enum · nullableOptional

Filter by transcript type

Possible values:

due_diligence_typestring · nullableOptional

Filter by due diligence type (BDD or MDD)

call_date_minstring · date-time · nullableOptional

Filter by minimum call date

call_date_maxstring · date-time · nullableOptional

Filter by maximum call date

length_mininteger · nullableOptional

Filter by minimum transcript length in characters

length_maxinteger · nullableOptional

Filter by maximum transcript length in characters

company_idstring · uuid · nullableOptional

Filter by associated company ID

company_namestring · nullableOptional

Search by associated company name

company_tickerstring · nullableOptional

Filter by associated company ticker

orderingstring · nullableOptional

Order results by field. Use '-' prefix for descending (e.g., 'project_affiliation', '-call_date', 'post_date', '-post_date')

pageinteger · min: 1Optional

Page number (starts from 1)

Default: 1

per_pageinteger · min: 1 · max: 100Optional

Number of items per page (max 100)

Default: 20

Header parameters

x-api-keystring · nullableOptional

Responses

200

Successful Response

application/json

422

Validation Error

application/json

get/api/v1/transcripts

GET /api/v1/transcripts HTTP/1.1
Accept: */*

{
  "data": [
    {
      "companies": [
        {
          "company_id": "123e4567-e89b-12d3-a456-426614174000",
          "company_name": "text",
          "stock_ticker": "text",
          "exchange": "text",
          "isin": "text"
        }
      ],
      "people": [
        {
          "person_id": "123e4567-e89b-12d3-a456-426614174000",
          "full_name": "text",
          "title": "text",
          "bio": "text"
        }
      ],
      "transcript_id": "123e4567-e89b-12d3-a456-426614174000",
      "call_date": "2026-01-01",
      "post_date": "2026-01-01",
      "project_affiliation": "text",
      "transcript_type": "conversation",
      "call_type": "text",
      "length": 1,
      "research_id": "123e4567-e89b-12d3-a456-426614174000",
      "transcript": [
        {
          "question": "text",
          "answer": "text"
        }
      ],
      "url": "text",
      "metadata": {
        "call_quality": "text",
        "call_tone": "text",
        "compliance_paragraph": "text"
      },
      "data_source_provider": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text"
      },
      "transcript_summary": "text"
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 1,
    "total_items": 1,
    "total_pages": 1,
    "has_next": true,
    "has_previous": true,
    "next_page": 1,
    "previous_page": 1
  }
}

Get Interview By Id

get

Get a specific interview by transcript ID.

Returns complete interview information including:

• Companies associated with the interview (including ISIN if available)
• People involved in the interview
• Transcript metadata (call date, post date, call type, etc.)
• Complete transcript content as question/answer pairs
• Metadata object with call quality and call tone

Path parameters

transcript_idstringRequired

Header parameters

x-api-keystring · nullableOptional

Responses

200

Successful Response

application/json

Interview response matching the desired API schema

transcript_idstring · uuidRequired

call_datestring · date · nullableRequired

post_datestring · date · nullableRequired

project_affiliationstringRequired

transcript_typestring · enum · nullableRequiredPossible values:

call_typestring · nullableRequired

lengthinteger · nullableRequired

research_idstring · uuid · nullableRequired

urlstringRequired

transcript_summarystring · nullableOptional

422

Validation Error

application/json

get/api/v1/transcripts/{transcript_id}

GET /api/v1/transcripts/{transcript_id} HTTP/1.1
Accept: */*

{
  "companies": [
    {
      "company_id": "123e4567-e89b-12d3-a456-426614174000",
      "company_name": "text",
      "stock_ticker": "text",
      "exchange": "text",
      "isin": "text"
    }
  ],
  "people": [
    {
      "person_id": "123e4567-e89b-12d3-a456-426614174000",
      "full_name": "text",
      "title": "text",
      "bio": "text"
    }
  ],
  "transcript_id": "123e4567-e89b-12d3-a456-426614174000",
  "call_date": "2026-01-01",
  "post_date": "2026-01-01",
  "project_affiliation": "text",
  "transcript_type": "conversation",
  "call_type": "text",
  "length": 1,
  "research_id": "123e4567-e89b-12d3-a456-426614174000",
  "transcript": [
    {
      "question": "text",
      "answer": "text"
    }
  ],
  "url": "text",
  "metadata": {
    "call_quality": "text",
    "call_tone": "text",
    "compliance_paragraph": "text"
  },
  "data_source_provider": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "text"
  },
  "transcript_summary": "text"
}