If your client does not list this tool, it is not available on your connection: the connection is read-only, or your role in the Space is Viewer (or no longer allows changes).
When to use
- “Build me a dashboard with spend, leads and cost per lead by campaign.”
- “Add a chart of leads by day to my Paid social dashboard.”
Before calling
- Get the
dashboard_idfromcreate_dashboardorlist_dashboards. - Call
get_report_builder_guideonce for the report config format. Metric slugs come fromlist_metric_catalogand custom event slugs fromlist_custom_events.
Parameters
Each report config:
A field you leave out gets the report builder’s default: all sources, the last 30 days, first touch attribution, the lifetime attribution window, no filters, and display options that suit the report type.
Example request
Example response
report_id: update_dashboard_report needs it.
skipped_existing lists the names of reports that were not created because the dashboard already has the same report (same name and same definition). Repeating a call therefore does not duplicate tiles. A report with the same name but another period, filter or attribution setting is a different report and is created.
Errors
- A config that cannot render fails the whole call. A missing
name,report_typeormetrics, an unknown metric slug, the wrong number ofgroup_bylevels for the type or a bad value returns avalidation_errorthat names the report and the field, for examplereports[1] ("Leads by day"). Nothing is saved. Fix that config and call again with the full list. - A few things are corrected instead of refused, and the guide notes each. For example, a
date_rangethe server doesn’t know, or a range sent without the dates it needs, is saved aslast_30_days, so checkdate_rangeincreated. not_foundwhen the dashboard isn’t in this Space, including IDs of dashboards in other Spaces.
Limits
- At most 12 new reports per call.
- A dashboard holds at most 40 reports. A call that would go over is refused whole.
- One person creates at most 60 reports an hour in a Space this way, across all of their connections. A call that would go over is refused whole with
rate_limited, and the message says how many are left and when the count starts over.
Caveats
- Not available to read-only connections, which include every connection made by a Viewer: the tool is hidden and calling it returns “Tool not found”.
- The call changes your Cometly data only. It makes no outbound request, touches no ad platform and uses no AI credits.
- Deleting a report, and moving or resizing tiles, are not possible through MCP. Do those in Cometly.