MCP Insights tutorial
Use IQM Model Context Protocol (MCP) to interact with the Insights API.
Overview
This tutorial guides you through using IQM MCP to generate Insights reports and templates.
Before you begin
To manage Insights reports using IQM MCP, the following are required:
- An account on the IQM platform
- See Before you begin to create an account and request a Client ID and Client Secret
- IQM MCP set up on your computer
- See the MCP Setup guide to set up MCP with your authorization credentials
- An audience and campaign that meet the eligibility requirements for generating Insights reports
- Audience Insights - Create Audience Insights report
- Audience Quality reports - AQ Insights report eligibility requirements
- Voter Level Data reports - VLD Insights eligibility requirements
- Script Lift Study reports - SLS Insights eligibility requirements
- Report templates - PLD Insights eligibility requirements
- Report templates - NLD Insights eligibility requirements
- Report templates - ICT Insights eligibility requirements
About IQM Insights
Insights reports are one of IQM's analytics tools that help Advertisers quickly identify trends and apply precise adjustments to deliver better results for campaigns.
With pre-defined metrics and dimensions, Insights reports can be generated for the following areas:
| Type | Description |
|---|---|
| Campaign Bidding Insights | Campaign Bidding Insights capture rejected campaigns and segment them based on rejection reason, allowing you to assess which parameters are limiting a campaign's success. |
| Audience Insights | Audience Insights provide in-depth reports of audience characteristics, interests, and behaviors to give you a deeper understanding of your target audience and create targeted and personalized advertising strategies. |
| Audience Quality (AQ) | AQ Insights leverage third-party healthcare data from PurpleLab to confirm audience exposure based on patient-level targeting criteria including prescriptions, diagnoses, and procedures. |
| Voter Level Data (VLD) | VLD Insights offer Insights about targeting in current or prior political campaigns. These reports include ad exposure, engagement data, demographic data, and voting-history details by voter. |
| Script Lift Study (SLS) | SLS Insights include key details about prescribing behaviors and how they're influenced by current and previous healthcare campaigns. |
| Provider Level Data (PLD) | PLD Insights include details about healthcare professionals targeted in your campaigns, and provide similar details as VLD Insights while adhering to healthcare data privacy regulations. |
| Nurse Level Data (NLD) | NLD Insights offer deeper visibility into how Non-NPI nurses engage with your campaigns. They uncover ad-exposure, engagement, demographic, and physician-specialty data to reveal reach and impact. |
| Integrated Care Team (ICT) | ICT Insights uncover key details about the ICT audiences you've targeted in previous and current campaigns. |
NOTE
Some Insights reports need to be enabled by an administrator before you can access them. By default, VLD, PLD, SLS, and AQ reports are not accessible to advertiser users.
You can check an advertiser's access to Insights reports with the Get Customer Config Details endpoint.
More resources
- Insights API guidelines
- Create an Insights report
- Reporting and analytics
- Audience Quality Insights reports
- Voter Level Data (VLD) Insights reports
- Script Lift Study (SLS) Insights reports
- Provider Level Data (PLD) Insights reports
- Nurse Level Data (NLD) Insights reports
- Integrated Care Team (ICT) Insights reports
Generate Audience Insights reports
You can use IQM MCP to generate Insights reports for eligible audiences. Use the following prompts to generate Insights reports for your audiences:
| Prompt | Response example | Notes |
|---|---|---|
| Show me a list of audiences eligible for generating Insights reports | Check for Insights-eligible audiences first, or provide an Audience ID directly to generate reports for. | |
| Generate an Insights report for each of those audiences | ||
| Create download links for each of those reports |
Create Insights report templates
You can also use IQM MCP to create Insights report templates for PLD, NLD, and ICT. Use the following prompts to create report templates:
| Prompt | Response example | Notes |
|---|---|---|
| Get a list of eligible audiences for the PLD templates for the healthcare Workspace | MCP notes that PLD templates require eligible campaigns, not audiences, and suggests the correct tool. | |
| Create a PLD template for campaign 590512 | MCP prompts the user for the necessary template details: frequency, aggregation, and name. MCP then uses tools to validate the name and find frequency details. | |
| Create an NLD template with these details: campaign 590516, frequency monthly, name "NLD Report 1", and not aggregated | MCP validates the request details and asks for any missing parameters. | |
| Get me a list of MCP templates | ||
| Update template 705 to be inactive, then update template 700 to weekly frequency | MCP notes that it has to update the start date in order to update the template correctly. |
Tools index
In the tables below you can find the complete set of Insights tools available in MCP, categorized by report type.
Each tool includes a brief description and a link to the corresponding API documentation for more details on its functionality and usage.
Use this index as a reference to explore the various Insights capabilities of MCP and how they relate to the Insights API endpoints.
Insights report details
| Tool name | Description | Documentation |
|---|---|---|
getInsightsDetailList | Get a list of Insights reports | Get a list of Insights reports |
getCampaignBiddingInsight | Get Campaign Bidding Insights data for a campaign | Get Campaign Bidding Insights |
getInsightsTypeWiseCount | Get Insights report counts grouped by type | Get Insights reports count by type |
getStatusWiseCampaignsForInsightsReports | Get a status-wise list of campaigns eligible for Insights reports | Get eligible campaigns |
computeInsightsReports | Compute Insights reports for the given campaigns | Calculate Insights computation |
Insights report management
| Tool name | Description | Documentation |
|---|---|---|
deleteInsights | Delete Insights report records by ID | Delete Insights report record |
regenerateInsights | Regenerate a failed Insights report | Regenerate Insights report |
sendInsightsEmail | Email an Insights report to recipients | Send Insights report email |
Audience Insights report
| Tool name | Description | Documentation |
|---|---|---|
getInsightsCreateEligibleAudienceList | Get a list of audiences eligible for Audience Insights report generation | Get a list of eligible audiences |
createInsightsDetails | Create an Audience Insights report for one or more audiences | Create Audience Insights report |
downloadInsights | Download an Audience Insights report (PDF or XLSX) | Download Insights report |
Power Segment Insights (PSI)
| Tool name | Description | Documentation |
|---|---|---|
generateReport | Generate a Power Segment Insights report | Generate PSI report |
getPowerSegmentsDetailList | Get a list of Power Segment Insights reports | Get Power Segment Insights list |
downloadReport | Download a Power Segment Insights report | Download PSI report |
sendReportEmail | Email a Power Segment Insights report to recipients | Email PSI report |
getPsiCategoryTypes | Get the list of Power Segment Insights category types | Get Power Segment Insights category types |
Audience Quality (AQ) Insights reports
| Tool name | Description | Documentation |
|---|---|---|
getReportDetailList | Get a paginated list of AQ Insights reports | Get list of AQ Insights reports |
getStatusWiseCampaignsForReports | Get a status-wise list of campaigns eligible for AQ Insights reports | Get list of campaigns eligible for AQ Insights reports |
validateAQSReportName | Validate an AQ Insights report name | Validate AQ Insights report name |
computeReports | Get cost and impression estimates for an AQ Insights report | Compute AQ Insights report cost |
generateAQReports | Generate an AQ Insights report | Generate AQ Insights report |
getAQSReportTypes | Get the list of available AQ Insights report types | Get AQ Insights report types |
getAQSReportDownloadUrl | Download an AQ Insights report | Download AQ Insights report |
deleteFailedReports | Delete a failed AQ Insights report | Delete AQ Insights report |
email | Email an AQ Insights report to recipients |
Voter Level Data (VLD) Insights reports
| Tool name | Description | Documentation |
|---|---|---|
getVLDReportList | Get a list of VLD Insights reports | Get list of VLD Insights reports |
getStatusWiseCampaignsForVLDReports | Get a list of campaigns eligible for VLD Insights reports | Get list of campaigns eligible for VLD Insights reports |
generateVLDReports | Generate a VLD Insights report | Generate VLD Insights report |
getChargeableImpressionsDataForVLDReports | Get cost and impression estimates for a VLD Insights report | Get cost assessment for VLD Insights report |
getVLDReportDownloadUrl | Download a VLD Insights report | Download VLD Insights report |
deleteFailedVLDReport | Delete a failed VLD Insights report | Delete VLD Insights report |
sendMailForVlDReport | Email a VLD Insights report to recipients |
Script Lift Study (SLS) Insights reports
| Tool name | Description | Documentation |
|---|---|---|
getSLSReportList | Get a list of SLS Insights reports | Get list of SLS Insights reports |
getStatusWiseCampaignsForSLSReports | Get a status-wise list of campaigns eligible for SLS Insights reports | Get list of campaigns eligible for SLS Insights reports |
generateSLSReports | Generate an SLS Insights report | Generate SLS Insights report |
getChargeableImpressionsDataForSLSReports | Get cost and impression estimates for an SLS Insights report | SLS Insights reports computation |
validateSlsReportName | Validate an SLS Insights report name | Validate SLS Insights report name |
getSLSReportDownloadUrl | Download an SLS Insights report | Download SLS Insights report |
deleteFailedSLSReport | Delete a failed SLS Insights report | Delete SLS Insights report |
sendMailForSlsReport | Email an SLS Insights report to recipients |
Provider Level Data (PLD) Insights reports
| Tool name | Description | Documentation |
|---|---|---|
getPLDReportList | Get a list of PLD Insights reports | |
generatePLDReports | Generate a PLD Insights report | |
getChargeableImpressionsDataForPLDReports | Get cost and impression estimates for a PLD Insights report | |
fetchPLDReportSelectedColumns | Get the user-selected columns for PLD Insights reports | |
saveOrUpdatePLDReportSelectedColumns | Save or update the user-selected columns for PLD Insights reports | |
getReportInterval | Get the reporting interval for a PLD Insights report template |
Report templates
| Tool name | Description | Documentation |
|---|---|---|
getTemplates | Get a list of report templates | Get list of templates |
createTemplate | Create a report template | Create report template |
updateTemplate | Update a report template | Update report template |
validateTemplateName | Validate a report template name | Validate template name |
getTemplateById | Get report template details by ID | Get template details |
getReportsForTemplate | Get the reports generated for a template | Get template reports |
Report management
| Tool name | Description | Documentation |
|---|---|---|
getReportDownloadUrl | Download an Insights report | Download report |
deleteFailedReport | Delete a failed report | Delete report |
sendMailForReport | Email an Insights report to recipients | Email report |
regenerateReports | Regenerate a failed schedulable report | Regenerate report |
Static / reference data
| Tool name | Description | Documentation |
|---|---|---|
getInsightsType | Get the list of Insights types | Get list of Insights types |
getInsightsStatus | Get the list of Insights status types | Get list of Insights status types |
getTemplateStatuses | Get the list of template status types | Get list of template status types |
getFrequencyMetadata | Get delivery frequency metadata for scheduling templates | Get scheduling frequencies |
getReportStatuses | Get the list of report statuses | |
getPropertiesOfReports | Get environment-wide default report properties |
Have a question?
Was this page helpful?