# Custom Dashboards

https://api-docs.lumar.io/docs/graphql/custom-dashboards

Custom dashboards let you build tailored views of your crawl and health score data. The data model consists of several related types:

- **Custom Dashboard Collection** -- a named group of dashboards, scoped to an account.
- **Custom Dashboard** -- a single dashboard within a collection, with a type such as `Trends`.
- **Custom Chart** -- a chart widget inside a dashboard, tracking a specific metric over time.
- **Custom Table** -- a tabular widget displaying metric data across crawls.
- **Custom View** -- links a project (and optionally a segment) to a dashboard, defining which data is displayed.

## Querying dashboards

Retrieve all dashboards for an account, including their charts:

```graphql
query GetCustomDashboards($accountId: ObjectID!) {
  getAccount(id: $accountId) {
    customDashboards(first: 10) {
      nodes {
        id
        name
        type
        createdAt
        customCharts(first: 5) {
          nodes {
            id
            metric
            type
          }
        }
      }
      totalCount
    }
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQ3MTU"
}
```

**Response:**
```json
{
  "data": {
    "getAccount": {
      "customDashboards": {
        "nodes": [
          {
            "id": "TjAzN0N1c3RvbURhc2hib2FyZDE",
            "name": "SEO Overview",
            "type": "Trends",
            "createdAt": "2025-01-10T08:00:00.000Z",
            "customCharts": {
              "nodes": [
                {
                  "id": "TjAzN0N1c3RvbUNoYXJ0MQ",
                  "metric": "all_pages_basic",
                  "type": "Line"
                }
              ]
            }
          }
        ],
        "totalCount": 1
      }
    }
  }
}
```

## Querying collections

Collections group dashboards together for organisation. Retrieve collections and their child dashboards:

```graphql
query GetDashboardCollections($accountId: ObjectID!) {
  getAccount(id: $accountId) {
    customDashboardCollections(first: 10) {
      nodes {
        id
        name
        customDashboards(first: 5) {
          nodes {
            id
            name
            type
          }
        }
      }
      totalCount
    }
  }
}
```

**Variables:**
```json
{
  "accountId": "TjAwN0FjY291bnQ3MTU"
}
```

**Response:**
```json
{
  "data": {
    "getAccount": {
      "customDashboardCollections": {
        "nodes": [
          {
            "id": "TjAzN0NvbGxlY3Rpb24x",
            "name": "Monthly Reports",
            "customDashboards": {
              "nodes": [
                {
                  "id": "TjAzN0N1c3RvbURhc2hib2FyZDE",
                  "name": "SEO Overview",
                  "type": "Trends"
                }
              ]
            }
          }
        ],
        "totalCount": 1
      }
    }
  }
}
```

## Creating a collection

Use the `createCustomDashboardCollection` mutation to create a new collection. You can optionally initialise it with default dashboards by passing `initCustomDashboards`.

```graphql
mutation CreateCustomDashboardCollection($input: CreateCustomDashboardCollectionInput!) {
  createCustomDashboardCollection(input: $input) {
    customDashboardCollection {
      id
      name
    }
  }
}
```

**Variables:**
```json
{
  "input": {
    "accountId": "TjAwN0FjY291bnQ3MTU",
    "name": "Monthly SEO Reports",
    "initCustomDashboards": ["Trends"]
  }
}
```

**Response:**
```json
{
  "data": {
    "createCustomDashboardCollection": {
      "customDashboardCollection": {
        "id": "TjAzN0NvbGxlY3Rpb24x",
        "name": "Monthly SEO Reports"
      }
    }
  }
}
```

## Creating a dashboard

Add a dashboard to an existing collection (or standalone) with the `createCustomDashboard` mutation.

```graphql
mutation CreateCustomDashboard($input: CreateCustomDashboardInput!) {
  createCustomDashboard(input: $input) {
    customDashboard {
      id
      name
      type
    }
  }
}
```

**Variables:**
```json
{
  "input": {
    "accountId": "TjAwN0FjY291bnQ3MTU",
    "name": "SEO Trends Dashboard",
    "type": "Trends",
    "customDashboardCollectionId": "TjAzN0NvbGxlY3Rpb24x"
  }
}
```

**Response:**
```json
{
  "data": {
    "createCustomDashboard": {
      "customDashboard": {
        "id": "TjAzN0N1c3RvbURhc2hib2FyZDE",
        "name": "SEO Trends Dashboard",
        "type": "Trends"
      }
    }
  }
}
```

## Working with views

Custom views associate a project and optional segment with a dashboard. When you add views to a dashboard, the charts and tables within it will display data for those projects.

Use the `addCustomViewsToCustomDashboard` mutation to link projects, or include `customViewIds` when creating a dashboard.

## Organising and copying

- **Reorder dashboards** within a collection using the `collectionPosition` field when updating a dashboard.
- **Copy a dashboard** using `copyCustomDashboard` -- this duplicates the dashboard and its charts into a target collection.
- **Copy a collection** using `copyCustomDashboardCollection` -- this duplicates the entire collection including all dashboards. Use `excludedCustomViewIds` to skip specific views during the copy.