> ## 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.

# update_dashboard_report

> Change one report on a Cometly dashboard: its name, type, metrics, grouping, sources, date range, attribution, filters or display options, with the old values returned for undo.

Changes one report on a dashboard in the Space: its name, type, metrics, grouping, sources, date range, attribution, filters or display options. The tile keeps its place and size. The response carries `previous`, the values the change replaced, so the change can be undone.

> [!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

* *"Make that a bar chart."*
* *"Use the last 90 days."*
* *"Add cost per lead to the campaign table."*

To correct a report the agent just created, change it here instead of creating a second one.

This overwrites the report, including one the user built by hand in Cometly. Call it only when it is clear which report the user means; if two reports could be meant, ask first.

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `report_id` | string | Yes | The ID of a report on a dashboard in this Space, from [`add_dashboard_reports`](https://docs.cometly.com/mcp/tools/add-dashboard-reports), [`get_dashboard`](https://docs.cometly.com/mcp/tools/get-dashboard) or [`list_reports`](https://docs.cometly.com/mcp/tools/list-reports). |
| `changes` | object | Yes | Only the config fields to change: any of `name`, `report_type`, `metrics`, `group_by`, `sources`, `date_range`, `date_start`, `date_end`, `attribution_model`, `attribution_window`, `query_mode`, `filters`, `options`, plus `options_mode` (see below). The format is in [`get_report_builder_guide`](https://docs.cometly.com/mcp/tools/get-report-builder-guide). |

## Semantics

* A field you leave out of `changes` keeps its value.
* An array field (`metrics`, `group_by`, `sources`) is replaced as a whole, so pass the complete new list.
* `options` is merged key by key. With `options_mode: "replace"` in `changes`, the `options` you pass become the report's options exactly.
* A change of type, metrics or grouping gives the report the display options that suit its new shape. Any other change (a name, a period, a source) leaves the report's look as it was.
* A `date_range` the server doesn't know, or a range sent without the dates it needs, is saved as `last_30_days`. Check `date_range` in the response.

## Example

Request:

```json theme={null}
{
  "report_id": "52002",
  "changes": { "name": "Leads by day (90 days)", "date_range": "last_90_days" }
}
```

Response:

```json theme={null}
{
  "success": true,
  "report": {
    "report_id": "52002",
    "name": "Leads by day (90 days)",
    "report_type": "area",
    "metrics": ["lead_generated"],
    "group_by": ["day"],
    "sources": [],
    "date_range": "last_90_days"
  },
  "previous": {
    "name": "Leads by day",
    "date_range": "last_30_days"
  }
}
```

## Undo

`previous` holds every field the update changed, as it was before, including fields that changed as a consequence (the dates of a custom range, the display options of the old shape). When the display options changed, `previous` carries the old `options` whole with `options_mode: "replace"`.

To undo a change, call `update_dashboard_report` again with the same `report_id` and `previous` as `changes`, unmodified.

## Errors

* `not_found` when no dashboard in this Space has a report with that ID, including reports in other Spaces.
* A config that cannot render returns a `validation_error` with the field named, and the report stays as it was.

## 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, moving it to another dashboard, and moving or resizing its tile are not possible through MCP. Do those in Cometly.


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