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

# Charts and dashboards

> Create, preview and edit dashboard charts from an AI tool with the MCP chart tools and the chart spec.

With the MCP chart tools, an AI tool can read your dashboards, run SQL on your events, preview a chart in the conversation and save it to a dashboard. Every chart is one **chart spec**: what it computes (the query) and how it is drawn (the view). The dashboard editor, Ask AI and the MCP tools write the same spec, and the API checks it the same way.

## Scopes

| Scope | Tools |
| - | - |
| `dashboards:read` | `list_dashboards`, `get_dashboard`, `list_charts`, `get_chart` |
| `analytics:read` | `describe_schema` |
| `query:read` | `execute_query`, `preview_chart` |
| `dashboards:write` | `create_dashboard`, `update_dashboard`, `delete_dashboard`, `create_chart`, `update_chart`, `delete_chart`, `duplicate_chart`, `move_chart`, `reorder_charts` |

`dashboards:write` does not include `dashboards:read`. A key that changes dashboards and also lists or reads them needs both scopes. A call to a tool without its scope returns an error that names the missing scope.

A key with `query:read` or `dashboards:write` acts for the person who created it. The audit log shows each change as that person, marked `via: mcp`. If that person leaves the workspace, the key stops working. If their role goes below **editor**, the key keeps only its read scopes. With OAuth, the person who approved the app is the actor.

## Workflow

1. `describe_schema` returns the `raw_events` and `sessions` columns, the context keys, the SQL rules, one example spec for each view feature and the custom events of the last 30 days.
2. `execute_query` runs your SQL and returns the result columns and up to 200 rows.
3. `preview_chart` runs a spec and returns the rows with the spec unchanged. In clients that support [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview), such as Claude, the chart shows in the conversation.
4. `create_chart` saves the spec on a dashboard. `update_chart` replaces the title and the spec. `delete_chart` and `delete_dashboard` need `"confirm": true`.

```json create_chart arguments theme={null}
{
  "boardId": "<dashboard id from list_dashboards or create_dashboard>",
  "title": "Daily page views",
  "description": "Last 30 days",
  "spec": {
    "version": 1,
    "query": { "kind": "sql", "sql": "SELECT toDate(received_at) AS day, uniqExactIf(message_id, type = 'page') AS pageviews FROM raw_events WHERE received_at >= toDateTime({{date_from}}) AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY GROUP BY day ORDER BY day" },
    "view": { "mark": "line", "encoding": { "x": { "field": "day" }, "y": { "field": "pageviews" } } }
  }
}
```

## How a spec is checked

* The spec has exactly `version` (always `1`), `query` and `view`. Unknown keys are refused.
* A SQL query runs once over the last 30 days. Every column that the view names must be a result column. A number card needs one row.
* Nothing is saved on a refusal. The error names the bad field, for example `Invalid chart spec: spec.view: The view names 'sessions', which the query result does not have. Result columns: day, pageviews, visitors`.
* A dashboard has up to 24 charts.

## SQL rules

* One `SELECT` or `WITH` statement over `raw_events`, `sessions` or `session_events`. No other table, no comments.
* For sessions, bounce rate and session duration, read `sessions` (one row for each session of the date range, the same sessions as the reports): `SELECT day, count() AS sessions FROM sessions GROUP BY day ORDER BY day`. Do not add a date condition to it, and never count sessions from `raw_events`.
* The server adds the project filter. You do not filter on `project_id`.
* Use `{{date_from}}` and `{{date_to}}` together: `received_at >= toDateTime({{date_from}}) AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY`. A saved chart then follows the dashboard date range.
* Return aggregates (`count()`, `uniqExact()`, `sum()`) grouped by the columns you chart.
* A query runs at most 8 seconds. A chart reads up to 1,000 rows.

`raw_events` columns: `anonymous_id`, `session_id`, `user_id`, `channel`, `type` (`page`, `track`, `identify`), `event`, `context` (JSON), `properties` (JSON), `original_timestamp`, `received_at`, `message_id`. Read context keys with `JSONExtractString(context,'utm_source')`; the page path is `JSONExtractString(context,'page','path')`.

`sessions` columns: `anonymous_id`, `session_key`, `day`, `first_at`, `last_at`, `pageviews`, `custom_events`, `revenue`, the landing columns of the first page view (`channel_type`, `utm_source`, `utm_medium`, `utm_campaign`, `referrer`, `ref`, `paid_source`, `country`), `entry_page`, `exit_page`. Name only the landing columns that the chart needs: each one uses memory, and a query over 256 MiB fails with a message that says so. See [Explorer](https://docs.manalens.dev/features/explorer.md#the-sessions-table).

## The view

The view is a small subset of [Vega-Lite](https://vega.github.io/vega-lite/). Each channel (`x`, `y`, `color`, `xOffset`, `yOffset`, `theta`, `text`) names one result column with `{ "field": "<column>" }` and never computes. Number formats are [d3-format](https://d3js.org/d3-format) strings: `"$,.2f"` money, `".1%"` percent (values are fractions), `".3~s"` compact, `",.0f"` integers.

## Examples

One example for each view feature. Funnel, retention and user paths charts have no SQL: the API builds their queries from the settings, so `preview_chart` does not draw them; save them on a dashboard to see them.

### Number

One value (1 row, 1 numeric column), or set encoding.text.field.

```json theme={null}
{
  "title": "Unique visitors",
  "spec": {
    "version": 1,
    "query": {
      "kind": "sql",
      "sql": "SELECT\n    uniqExactIf(anonymous_id, anonymous_id != '') AS visitors\nFROM raw_events\nWHERE type IN ('page','track')\n    AND received_at >= toDateTime({{date_from}})\n    AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY\n    AND JSONExtractString(context,'device') != 'bot'"
    },
    "view": {
      "mark": "text",
      "encoding": {}
    }
  }
}
```

### Number format

Money, fractions (0.25 = 25%) or large counts: a d3 format on text or on an axis.

```json theme={null}
{
  "title": "Revenue",
  "spec": {
    "version": 1,
    "query": {
      "kind": "sql",
      "sql": "SELECT\n    sumIf(JSONExtractFloat(properties,'revenue'), type = 'track' AND JSONHas(properties,'revenue')) AS revenue\nFROM raw_events\nWHERE type = 'track'\n    AND received_at >= toDateTime({{date_from}})\n    AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY\n    AND JSONExtractString(context,'device') != 'bot'"
    },
    "view": {
      "mark": "text",
      "encoding": {
        "text": {
          "field": "revenue",
          "format": "$,.2f"
        }
      }
    }
  }
}
```

### Table

Several columns to read, not to compare visually.

```json theme={null}
{
  "title": "Top pages",
  "spec": {
    "version": 1,
    "query": {
      "kind": "sql",
      "sql": "SELECT\n    JSONExtractString(context,'page','path') AS page,\n    uniqExact(message_id) AS pageviews\nFROM raw_events\nWHERE type = 'page'\n    AND received_at >= toDateTime({{date_from}})\n    AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY\n    AND JSONExtractString(context,'device') != 'bot'\nGROUP BY page\nORDER BY pageviews DESC\nLIMIT 10"
    },
    "view": {
      "mark": "x-table"
    }
  }
}
```

### Line

A time series with one metric.

```json theme={null}
{
  "title": "Daily page views",
  "spec": {
    "version": 1,
    "query": {
      "kind": "sql",
      "sql": "SELECT\n    toDate(received_at) AS day,\n    uniqExactIf(message_id, type = 'page') AS pageviews,\n    uniqExactIf(anonymous_id, anonymous_id != '') AS visitors\nFROM raw_events\nWHERE type IN ('page','track')\n    AND received_at >= toDateTime({{date_from}})\n    AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY\n    AND JSONExtractString(context,'device') != 'bot'\nGROUP BY day\nORDER BY day"
    },
    "view": {
      "mark": "line",
      "encoding": {
        "x": {
          "field": "day"
        },
        "y": {
          "field": "pageviews"
        }
      }
    }
  }
}
```

### Area

Volume over time.

```json theme={null}
{
  "title": "Daily visitors",
  "spec": {
    "version": 1,
    "query": {
      "kind": "sql",
      "sql": "SELECT\n    toDate(received_at) AS day,\n    uniqExactIf(message_id, type = 'page') AS pageviews,\n    uniqExactIf(anonymous_id, anonymous_id != '') AS visitors\nFROM raw_events\nWHERE type IN ('page','track')\n    AND received_at >= toDateTime({{date_from}})\n    AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY\n    AND JSONExtractString(context,'device') != 'bot'\nGROUP BY day\nORDER BY day"
    },
    "view": {
      "mark": "area",
      "encoding": {
        "x": {
          "field": "day"
        },
        "y": {
          "field": "visitors"
        }
      }
    }
  }
}
```

### Bar

Categories or a top N list.

```json theme={null}
{
  "title": "Page views by page",
  "spec": {
    "version": 1,
    "query": {
      "kind": "sql",
      "sql": "SELECT\n    JSONExtractString(context,'page','path') AS page,\n    uniqExact(message_id) AS pageviews\nFROM raw_events\nWHERE type = 'page'\n    AND received_at >= toDateTime({{date_from}})\n    AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY\n    AND JSONExtractString(context,'device') != 'bot'\nGROUP BY page\nORDER BY pageviews DESC\nLIMIT 10"
    },
    "view": {
      "mark": "bar",
      "encoding": {
        "x": {
          "field": "page"
        },
        "y": {
          "field": "pageviews"
        }
      }
    }
  }
}
```

### Several value columns (fold)

Wide rows: one series per metric column. The as names must not be result columns.

```json theme={null}
{
  "title": "Page views and visitors",
  "spec": {
    "version": 1,
    "query": {
      "kind": "sql",
      "sql": "SELECT\n    toDate(received_at) AS day,\n    uniqExactIf(message_id, type = 'page') AS pageviews,\n    uniqExactIf(anonymous_id, anonymous_id != '') AS visitors\nFROM raw_events\nWHERE type IN ('page','track')\n    AND received_at >= toDateTime({{date_from}})\n    AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY\n    AND JSONExtractString(context,'device') != 'bot'\nGROUP BY day\nORDER BY day"
    },
    "view": {
      "mark": "line",
      "transform": [
        {
          "fold": [
            "pageviews",
            "visitors"
          ],
          "as": [
            "series",
            "value"
          ]
        }
      ],
      "encoding": {
        "x": {
          "field": "day"
        },
        "y": {
          "field": "value"
        },
        "color": {
          "field": "series"
        }
      }
    }
  }
}
```

### Split line

Long rows: one line per value of a breakdown column (color differs from x).

```json theme={null}
{
  "title": "Page views by channel",
  "spec": {
    "version": 1,
    "query": {
      "kind": "sql",
      "sql": "SELECT\n    toDate(received_at) AS day,\n    if(JSONExtractString(context,'channel_type') != '', JSONExtractString(context,'channel_type'), 'Direct') AS channel,\n    uniqExact(message_id) AS pageviews\nFROM raw_events\nWHERE type = 'page'\n    AND received_at >= toDateTime({{date_from}})\n    AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY\n    AND JSONExtractString(context,'device') != 'bot'\nGROUP BY day, channel\nORDER BY day, channel"
    },
    "view": {
      "mark": "line",
      "encoding": {
        "x": {
          "field": "day"
        },
        "y": {
          "field": "pageviews"
        },
        "color": {
          "field": "channel"
        }
      }
    }
  }
}
```

### Stacked bars

The total and its parts per x.

```json theme={null}
{
  "title": "Page views by channel, stacked",
  "spec": {
    "version": 1,
    "query": {
      "kind": "sql",
      "sql": "SELECT\n    toDate(received_at) AS day,\n    if(JSONExtractString(context,'channel_type') != '', JSONExtractString(context,'channel_type'), 'Direct') AS channel,\n    uniqExact(message_id) AS pageviews\nFROM raw_events\nWHERE type = 'page'\n    AND received_at >= toDateTime({{date_from}})\n    AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY\n    AND JSONExtractString(context,'device') != 'bot'\nGROUP BY day, channel\nORDER BY day, channel"
    },
    "view": {
      "mark": "bar",
      "encoding": {
        "x": {
          "field": "day"
        },
        "y": {
          "field": "pageviews",
          "stack": true
        },
        "color": {
          "field": "channel"
        }
      }
    }
  }
}
```

### 100% stacked

Shares or mix over time: each x adds up to 100%. Also with mark area.

```json theme={null}
{
  "title": "Channel mix",
  "spec": {
    "version": 1,
    "query": {
      "kind": "sql",
      "sql": "SELECT\n    toDate(received_at) AS day,\n    if(JSONExtractString(context,'channel_type') != '', JSONExtractString(context,'channel_type'), 'Direct') AS channel,\n    uniqExact(message_id) AS pageviews\nFROM raw_events\nWHERE type = 'page'\n    AND received_at >= toDateTime({{date_from}})\n    AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY\n    AND JSONExtractString(context,'device') != 'bot'\nGROUP BY day, channel\nORDER BY day, channel"
    },
    "view": {
      "mark": "area",
      "encoding": {
        "x": {
          "field": "day"
        },
        "y": {
          "field": "pageviews",
          "stack": "normalize"
        },
        "color": {
          "field": "channel"
        }
      }
    }
  }
}
```

### Grouped bars

Compare a few series side by side per x (xOffset equals color).

```json theme={null}
{
  "title": "Weekly visitors by device",
  "spec": {
    "version": 1,
    "query": {
      "kind": "sql",
      "sql": "SELECT\n    toStartOfWeek(received_at, 1) AS week,\n    JSONExtractString(context,'device') AS device,\n    uniqExactIf(anonymous_id, anonymous_id != '') AS visitors\nFROM raw_events\nWHERE type = 'page'\n    AND received_at >= toDateTime({{date_from}})\n    AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY\n    AND JSONExtractString(context,'device') != 'bot'\nGROUP BY week, device\nORDER BY week, device"
    },
    "view": {
      "mark": "bar",
      "encoding": {
        "x": {
          "field": "week"
        },
        "y": {
          "field": "visitors"
        },
        "color": {
          "field": "device"
        },
        "xOffset": {
          "field": "device"
        }
      }
    }
  }
}
```

### Horizontal bars

Rankings with long labels: a nominal y and a quantitative x.

```json theme={null}
{
  "title": "Top pages",
  "spec": {
    "version": 1,
    "query": {
      "kind": "sql",
      "sql": "SELECT\n    JSONExtractString(context,'page','path') AS page,\n    uniqExact(message_id) AS pageviews\nFROM raw_events\nWHERE type = 'page'\n    AND received_at >= toDateTime({{date_from}})\n    AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY\n    AND JSONExtractString(context,'device') != 'bot'\nGROUP BY page\nORDER BY pageviews DESC\nLIMIT 10"
    },
    "view": {
      "mark": "bar",
      "encoding": {
        "y": {
          "field": "page",
          "type": "nominal"
        },
        "x": {
          "field": "pageviews",
          "type": "quantitative"
        }
      }
    }
  }
}
```

### Pie

Proportions of 2 to 10 categories.

```json theme={null}
{
  "title": "Visitors by source",
  "spec": {
    "version": 1,
    "query": {
      "kind": "sql",
      "sql": "SELECT\n    if(JSONExtractString(context,'utm_source') != '', JSONExtractString(context,'utm_source'), 'Direct') AS source,\n    uniqExactIf(anonymous_id, anonymous_id != '') AS visitors\nFROM raw_events\nWHERE type = 'page'\n    AND received_at >= toDateTime({{date_from}})\n    AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY\n    AND JSONExtractString(context,'device') != 'bot'\nGROUP BY source\nORDER BY visitors DESC\nLIMIT 8"
    },
    "view": {
      "mark": "arc",
      "encoding": {
        "theta": {
          "field": "visitors",
          "aggregate": "sum"
        },
        "color": {
          "field": "source"
        }
      }
    }
  }
}
```

### Scatter

Whether two numbers move together: one point per row.

```json theme={null}
{
  "title": "Page views and events per day",
  "spec": {
    "version": 1,
    "query": {
      "kind": "sql",
      "sql": "SELECT\n    toDate(received_at) AS day,\n    countIf(type = 'page') AS pageviews,\n    countIf(type = 'track') AS events\nFROM raw_events\nWHERE type IN ('page','track')\n    AND received_at >= toDateTime({{date_from}})\n    AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY\n    AND JSONExtractString(context,'device') != 'bot'\nGROUP BY day\nORDER BY day"
    },
    "view": {
      "mark": "point",
      "encoding": {
        "x": {
          "field": "pageviews"
        },
        "y": {
          "field": "events"
        }
      }
    }
  }
}
```

### Combo

A count and a rate on the same x, each with its own axis: one bar layer and one line layer.

```json theme={null}
{
  "title": "Signups and conversion rate",
  "spec": {
    "version": 1,
    "query": {
      "kind": "sql",
      "sql": "SELECT\n    toDate(received_at) AS day,\n    countIf(type = 'track' AND event = 'signup_completed') AS signups,\n    if(uniqExactIf(anonymous_id, anonymous_id != '') = 0, 0, uniqExactIf(anonymous_id, event = 'signup_completed') / uniqExactIf(anonymous_id, anonymous_id != '')) AS conversion_rate\nFROM raw_events\nWHERE type IN ('page','track')\n    AND received_at >= toDateTime({{date_from}})\n    AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY\n    AND JSONExtractString(context,'device') != 'bot'\nGROUP BY day\nORDER BY day"
    },
    "view": {
      "layer": [
        {
          "mark": "bar",
          "encoding": {
            "x": {
              "field": "day"
            },
            "y": {
              "field": "signups"
            }
          }
        },
        {
          "mark": "line",
          "encoding": {
            "x": {
              "field": "day"
            },
            "y": {
              "field": "conversion_rate",
              "axis": {
                "format": ".1%"
              }
            }
          }
        }
      ],
      "resolve": {
        "scale": {
          "y": "independent"
        }
      }
    }
  }
}
```

### Goal line

Only when the user states a target: a rule layer with a y datum.

```json theme={null}
{
  "title": "Daily visitors against a goal",
  "spec": {
    "version": 1,
    "query": {
      "kind": "sql",
      "sql": "SELECT\n    toDate(received_at) AS day,\n    uniqExactIf(message_id, type = 'page') AS pageviews,\n    uniqExactIf(anonymous_id, anonymous_id != '') AS visitors\nFROM raw_events\nWHERE type IN ('page','track')\n    AND received_at >= toDateTime({{date_from}})\n    AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY\n    AND JSONExtractString(context,'device') != 'bot'\nGROUP BY day\nORDER BY day"
    },
    "view": {
      "layer": [
        {
          "mark": "line",
          "encoding": {
            "x": {
              "field": "day"
            },
            "y": {
              "field": "visitors"
            }
          }
        },
        {
          "mark": "rule",
          "encoding": {
            "y": {
              "datum": 100
            }
          }
        }
      ]
    }
  }
}
```

### Goal line on the right axis

A target for the line of a combo with resolve.scale.y "independent": nest the line and its rule in one layer, so the rule uses the right axis. A rule outside the nested layer is on the left (bars) axis.

```json theme={null}
{
  "title": "Signups and conversion rate against a goal",
  "spec": {
    "version": 1,
    "query": {
      "kind": "sql",
      "sql": "SELECT\n    toDate(received_at) AS day,\n    countIf(type = 'track' AND event = 'signup_completed') AS signups,\n    if(uniqExactIf(anonymous_id, anonymous_id != '') = 0, 0, uniqExactIf(anonymous_id, event = 'signup_completed') / uniqExactIf(anonymous_id, anonymous_id != '')) AS conversion_rate\nFROM raw_events\nWHERE type IN ('page','track')\n    AND received_at >= toDateTime({{date_from}})\n    AND received_at < toDateTime({{date_to}}) + INTERVAL 1 DAY\n    AND JSONExtractString(context,'device') != 'bot'\nGROUP BY day\nORDER BY day"
    },
    "view": {
      "layer": [
        {
          "mark": "bar",
          "encoding": {
            "x": {
              "field": "day"
            },
            "y": {
              "field": "signups"
            }
          }
        },
        {
          "layer": [
            {
              "mark": "line",
              "encoding": {
                "x": {
                  "field": "day"
                },
                "y": {
                  "field": "conversion_rate",
                  "axis": {
                    "format": ".1%"
                  }
                }
              }
            },
            {
              "mark": "rule",
              "encoding": {
                "y": {
                  "datum": 0.05
                }
              }
            }
          ]
        }
      ],
      "resolve": {
        "scale": {
          "y": "independent"
        }
      }
    }
  }
}
```

### Funnel

Conversion through 2 to 5 ordered steps (no SQL; save it on a dashboard to see it).

```json theme={null}
{
  "title": "Signup funnel",
  "spec": {
    "version": 1,
    "query": {
      "kind": "funnel",
      "steps": [
        {
          "type": "page",
          "value": "/"
        },
        {
          "type": "track",
          "value": "signup_completed"
        }
      ],
      "settings": {
        "window_seconds": 86400,
        "funnel_type": "closed"
      }
    },
    "view": {
      "mark": "x-funnel"
    }
  }
}
```

### Retention

Share of visitors who come back each period (no SQL).

```json theme={null}
{
  "title": "Weekly retention",
  "spec": {
    "version": 1,
    "query": {
      "kind": "retention",
      "settings": {}
    },
    "view": {
      "mark": "x-retention"
    }
  }
}
```

### User paths

How people move from page to page (no SQL).

```json theme={null}
{
  "title": "User flow",
  "spec": {
    "version": 1,
    "query": {
      "kind": "paths",
      "settings": {}
    },
    "view": {
      "mark": "x-sankey"
    }
  }
}
```


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