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

# create_dashboard

> Create a new, empty dashboard in a Cometly space by name and get back its dashboard_id, so add_dashboard_reports can put reports on it.

Creates a new, empty dashboard in the Space and returns its `dashboard_id`. Put reports on it with [`add_dashboard_reports`](https://docs.cometly.com/mcp/tools/add-dashboard-reports).

> [!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 paid social dashboard."*
* *"Make a dashboard for the SEO team."*

To add reports to a dashboard that already exists, skip this tool and call [`add_dashboard_reports`](https://docs.cometly.com/mcp/tools/add-dashboard-reports) with the dashboard's ID from [`list_dashboards`](https://docs.cometly.com/mcp/tools/list-dashboards).

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `name` | string | Yes | The dashboard name shown in Cometly, up to 255 characters. |

## Example response

```json theme={null}
{
  "success": true,
  "dashboard": {
    "dashboard_id": "8123",
    "name": "Paid social"
  },
  "where_to_find_it": "In Cometly, open Dashboard in the \"Acme Marketing\" space and choose \"Paid social\" in the dashboard picker at the top of the page."
}
```

A dashboard has no link of its own, so pass `where_to_find_it` on to the user. In Cometly, the dashboard is in the dashboard dropdown at the top left of **Dashboard** (see [Customize your dashboards](https://docs.cometly.com/guides/dashboards/customize.md)).

## Limits

* **One name per dashboard.** A name already used by a dashboard in the Space is refused with a `validation_error`. Names are compared without regard to case or surrounding spaces. The message gives that dashboard's `dashboard_id`, so the agent can add reports to it or ask for another name. A retried call is therefore harmless: it finds the dashboard the first call created.
* **50 dashboards per Space.** No dashboard is created once the Space has 50.
* **10 an hour.** One person creates at most 10 dashboards an hour in a Space this way, across all of their connections: a second connection does not add to the limit. After that the tool returns `rate_limited`, and the message says when the count starts over.
* **One at a time per Space.** If another dashboard is being created in the same Space at that moment, the call may return `rate_limited` and create nothing. Call `list_dashboards` before retrying: the dashboard may already be there.

## 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.
* Renaming or deleting a dashboard, and moving or resizing its 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.