MCP reports tutorial
Use IQM Model Context Protocol (MCP) to interact with the Reports API.
Overview
This tutorial guides you through using IQM MCP to manage reports on the IQM platform. You learn how to create, execute, and schedule reports using MCP prompts.
Before you begin
To manage 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 the MCP with your authorization credentials
- At least one active campaign on the IQM platform
- See the Create a campaign quickstart guide
About IQM reports
IQM reports allow you to track various metrics of campaign performance. You can create custom reports to analyze data such as impressions, clicks, conversions, and revenue across different dimensions like time, geography, device type, and more.
Reports can be either daily or aggregated. The daily report includes the date as a dimension and provides the data breakdown by date.
You can run a report containing up to three months of data for any dimension combination, or up to one year for the campaign dimension. You must run multiple reports if you need more than that amount of data.
More resources
- Reports API guidelines
- Run a report quickstart guide
- Schedule a report quickstart guide
- Reports overview Help Center article
Execute a report
You can use IQM MCP to execute a report on demand. Follow the steps below to execute a report using MCP prompts.
Step 1: Request metrics and dimensions
Choose the dimensions and metrics desired for the report. Reports are in table format, where the metrics comprise the columns and the dimensions comprise the rows.
See the complete Get dimensions and metrics details API documentation and the Report dimensions and metrics Help Center article for more information on available dimensions and metrics.
Try the following prompt to get a list of available dimensions and metrics:
| Prompt | Response example | Notes |
|---|---|---|
| Show me a list of reporting metrics and dimensions | MCP retrieves a list of available reporting metrics and dimensions with IDs and descriptions. |
Step 2: Select a timezone
Once metrics and dimensions are chosen, choose a timezone to target. Only one timezone can be included per report. Run multiple reports to see results for multiple timezones.
Try the following prompt to get a list of available timezones:
| Prompt | Response example | Notes |
|---|---|---|
| Show me a list of US timezone IDs | MCP retrieves a list of available US timezone IDs with descriptions. You can specify by region, country, or specific timezone name. |
Step 3: Execute a report
Now that you have selected the desired metrics, dimensions, and timezone, you can create and execute a report. Try the following prompts to create and execute a report:
| Prompt | Response example | Notes |
|---|---|---|
| I want to execute a report | MCP asks for the necessary metrics, dimensions, and other request parameters to execute the report. | |
| Execute a report for CMP0001 and its associated creatives for the impressions and CTR metrics. Date range for the month of December 2025 in the EST timezone. Daily data |
Create and schedule a report
You can also use IQM MCP to create, update, and schedule reports for regular delivery. Follow the steps below to create and schedule a report using MCP prompts.
Step 1: Create a report
| Prompt | Response example | Notes |
|---|---|---|
| I want to create a report | MCP asks for the necessary metrics, dimensions, and other request parameters to create the report. | |
| Create a report with the following parameters: Name: Report 001. Time period: Jan 2026 - March. Dimensions: Creative, device type, campaign. Metrics: impressions, clicks, ctr, spent, conversions. Aggregated | NOTE The date range for a report cannot exceed one year. | |
| Create another report with all the same criteria but daily and for November 2025 | ||
| Update report ID 14018 to have name: Report 002 |
Step 2: Schedule the report
| Prompt | Response example | Notes |
|---|---|---|
| I want to make a schedule for report 002 | MCP asks for the necessary parameters to create a schedule for the report. | |
| Create a schedule for Report 002 with the following criteria: Frequency: Monthly; End Date: March 3, 2026; Delivery day: 6. Emails: user1@iqm.com | ||
| Update that schedule to be weekly, every Tuesday |
More report actions
You can also use IQM MCP to delete reports, cancel report schedules, or get a list of reports. Try the following prompts:
| Prompt | Response example | Notes |
|---|---|---|
| Get a list of reports with details in a simple table | MCP retrieves a list of available reports with details. You can specify filters and sorting options. | |
| Remove the scheduling for report 002 | MCP cancels the schedule for the specified report. The report still exists and can be executed. | |
| Delete report 002 | MCP deletes the specified report. This action is irreversible. |
Tools index
In the tables below you can find the complete set of report tools available in the MCP, categorized by function.
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 report management capabilities of the MCP and how they relate to the Reports API endpoints.
Report details
| Tool name | Description | Documentation |
|---|---|---|
getReportList | Get a list of reports | Get a list of reports |
fetchReportList | Get a list of reports with filters | |
getReport | Get report details by ID | Get report by ID |
Reports management
| Tool name | Description | Documentation |
|---|---|---|
saveReport | Create a new report | Create report |
executeReportData | Execute a report and fetch serving data | Execute a report |
updateReport | Edit an existing report | Edit a report |
deleteReport | Delete a report and its scheduling data | Delete a report |
Scheduling management
| Tool name | Description | Documentation |
|---|---|---|
saveReportScheduleEvent | Schedule email delivery for a report | Schedule a report |
updateReportScheduleEvent | Update a report's email schedule | Update a report schedule |
deleteReportScheduleEvent | Remove a report's email schedule | Delete report schedule |
More report details
| Tool name | Description | Documentation |
|---|---|---|
getDimensionAndMetricDetails | Get available dimensions and metrics for reports | Get dimensions and metrics details |
Video demo
Follow along with this video demo of the reports tutorial: