Custom dashboards

The Dashboard page in the sidebar holds the charts you ask for, and nothing else. You fill it by asking your coding agent, which adds charts through the StepMetrics MCP server. There is no chart builder in the dashboard: say what you want to see, and the next time the page loads it is there.

It starts blank

A new workspace has an empty Dashboard page. Until your agent adds a chart, the page shows example requests you can copy and give to your agent. The Overview is separate and does not change: it always shows the visitors chart, and on All sites a bar chart of your shared metrics once you have some.

Shared metrics

A shared metric is one outcome, such as Signups, counted across sites that name it differently. For example, signup on one site and registered on another can both count as Signups. A workspace has up to six, and each one keeps the same colour on every chart and on its tile. They count events, not people, and they do not add up revenue. Ask your agent to create them, for example “Create a shared metric called Signups from the signup event on each of my sites.”

Ratio metrics

A ratio metric divides one count by another: prompts answered out of prompts shown, or signups per 1,000 engaged visits. Each side is either a custom event or a traffic number the Overview already shows: visitors, visits, engaged visits or pageviews. Both sides are counted on the same sites you name, over the same period, with bots left out. Choose how it reads: a percentage, a plain ratio, or per 100, 1,000 or 10,000 of the thing you divide by.

Every ratio comes with the two counts it divided, so you can check it by hand. When nothing was counted underneath it, such as a week in which no prompt was shown, it says no data, never 0%. Ratios appear as tiles on the Overview: all of them on All sites, and on a site's own page the ones counted on that site alone. A workspace has up to twelve. Ask your agent, for example “Add a ratio metric called Yes rate: prompt_yes events out of prompt_answered events on my app, as a percentage.”

What a chart can show

• Any mix of visitors, pageviews and your shared metrics, up to eight series.
• Over time, as bars side by side, stacked bars, or lines. Stack only series that are parts of one whole.
• For the period as a whole, as totals: one bar per series, to compare them with each other.
• Every site, or only the sites you name. A chart with no site list picks up sites you add later.
• The period chosen at the top of the page. Site and segment filters do not apply here: each chart names its own sites.

The page holds up to twelve charts, in the order your agent sets. Visitors summed across sites count someone who read two of them twice, and the chart says so.

Asking your agent

Connect your agent from the dashboard's Connect agent button, as described in Connect an agent over MCP. The key it gives your agent can read your analytics and build this page, but cannot create keys, delete your data or sites, or touch billing. An agent connected earlier with a read-only key is refused; connect it again. A read key can see the charts with get_dashboard but cannot change them. Then ask in plain words, for example:

• “Add a bar chart of all my shared metrics to my StepMetrics dashboard.”
• “Compare the totals of all my shared metrics for the period in one bar chart.”
• “Chart visitors and pageviews across all my sites as lines.”
• “Show visitors and signups for my blog as lines, and move that chart to the top.”
• “Show signups per 1,000 engaged visits for my blog.”
• “Clear my dashboard.”

The tools your agent uses:

A change that would break a chart is refused with a sentence saying what to fix. For example, deleting a shared metric that a chart still draws fails until the chart is changed. If a chart ever cannot be drawn, it says why on the page instead of showing a partial picture.

Over the API

GET    /v1/dashboard-charts     the charts, in order                        read key
PUT    /v1/dashboard-charts     replace every chart                         edit key
DELETE /v1/dashboard-charts     remove every chart                          edit key
GET    /v1/dashboard?period=7d  each chart with its numbers                 read key
GET    /v1/ratio-metrics        each ratio with both counts and its value   read key
PUT    /v1/ratio-metrics        replace every ratio                         edit key

The page is a list of charts:

[
  {
    "id": "outcomes",
    "type": "metrics",
    "title": "Signups and purchases",
    "display": "bars",
    "series": [
      { "type": "shared_metric", "metric": "Signups" },
      { "type": "shared_metric", "metric": "Purchases" },
      { "type": "visitors" }
    ],
    "siteIds": ["00000000-0000-4000-8000-000000000001"]
  }
]

display is bars, stacked, lines or totals. Leave out siteIds to include every site. Send [] for a blank page. GET /v1/dashboard returns buckets, the start of each day, week or month, and one value per bucket for every series, totals charts included. The charts are stored as dashboardCharts in the workspace's configuration, so they can also be set through PATCH /v1/orgs/:orgId.

A ratio metric looks like this:

{
  "label": "Signups per 1,000 engaged visitors",
  "numerator": { "type": "event", "event": "signup" },
  "denominator": { "type": "engaged_visitors" },
  "unit": "per_1000",
  "siteIds": ["00000000-0000-4000-8000-000000000001"]
}

unit is percent, ratio, per_100, per_1000 or per_10000. Each result has current and previous, each with numerator, denominator, value and display. value is the numerator times scale divided by the denominator; a percentage is reported as a fraction, so 0.25 is 25%. It is null, and display is no data, when the denominator is 0. Ratios are stored as ratioMetrics in the workspace's configuration.

To chart a ratio over time, add { "type": "ratio_metric", "metric": "Signups per 1,000 engaged visitors" } to a chart's series. Each day divides that day's two counts, and a day with nothing to divide by is left blank rather than shown as 0. A chart of ratios holds only ratios, all in the same unit, and cannot be stacked.