> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cometly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# add_dashboard_reports

> Create one or more reports on a Cometly dashboard in a single all-or-nothing call and place them below the reports already there.

Creates one or more reports on a dashboard in the Space and places them below the reports already there. The reports are saved at once and show live data the next time the user opens the dashboard in Cometly.

> [!NOTE]
>
> 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."*

Pass every report of a request in **one** call, in the order they should appear. Related reports then land side by side, and the set is saved together or not at all.

## Before calling

* Get the `dashboard_id` from [`create_dashboard`](https://docs.cometly.com/mcp/tools/create-dashboard) or [`list_dashboards`](https://docs.cometly.com/mcp/tools/list-dashboards).
* Call [`get_report_builder_guide`](https://docs.cometly.com/mcp/tools/get-report-builder-guide) once for the report config format. Metric slugs come from [`list_metric_catalog`](https://docs.cometly.com/mcp/tools/list-metric-catalog) and custom event slugs from [`list_custom_events`](https://docs.cometly.com/mcp/tools/list-custom-events).

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `dashboard_id` | string | Yes | The ID of a dashboard in this Space. |
| `reports` | array | Yes | 1 to 12 report configs, in display order. |

Each report config:

| Field | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | The report title on the dashboard. |
| `report_type` | string | Yes | `summary`, `line`, `area`, `column`, `bar`, `combo`, `pie`, or `table`. |
| `metrics` | array of strings | Yes | Metric slugs from `list_metric_catalog`. At least one. |
| `group_by` | array of strings | No | 0 to 2 groupings, depending on the type. |
| `sources`, `date_range`, `date_start`, `date_end`, `attribution_model`, `attribution_window`, `query_mode`, `filters`, `options` | | No | The accepted values are in [`get_report_builder_guide`](https://docs.cometly.com/mcp/tools/get-report-builder-guide). |
| `width` | string | No | `third`, `half`, or `full`. Default: `full` for a summary or a table, `half` for a chart. |

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

```json theme={null}
{
  "dashboard_id": "8123",
  "reports": [
    { "name": "Overview", "report_type": "summary", "metrics": ["amount_spent", "lead_generated", "cost_per_lead_generated"] },
    { "name": "Leads by day", "report_type": "area", "metrics": ["lead_generated"], "group_by": ["day"] }
  ]
}
```

## Example response

```json theme={null}
{
  "success": true,
  "dashboard": { "dashboard_id": "8123", "name": "Paid social" },
  "created": [
    {
      "report_id": "52001",
      "name": "Overview",
      "report_type": "summary",
      "metrics": ["amount_spent", "lead_generated", "cost_per_lead_generated"],
      "group_by": [],
      "sources": [],
      "date_range": "last_30_days"
    },
    {
      "report_id": "52002",
      "name": "Leads by day",
      "report_type": "area",
      "metrics": ["lead_generated"],
      "group_by": ["day"],
      "sources": [],
      "date_range": "last_30_days"
    }
  ],
  "skipped_existing": []
}
```

Keep each `report_id`: [`update_dashboard_report`](https://docs.cometly.com/mcp/tools/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_type` or `metrics`, an unknown metric slug, the wrong number of `group_by` levels for the type or a bad value returns a `validation_error` that names the report and the field, for example `reports[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_range` the server doesn't know, or a range sent without the dates it needs, is saved as `last_30_days`, so check `date_range` in `created`.
* `not_found` when 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](https://docs.cometly.com/mcp/authentication.md#read-only-tokens), 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.