Dashboards

Dashboards

A DashboardV2 has a shared dashboardContext input (global theme) and widgets that inherit it by default. Each widget is either a chart (Advanced Explorer queries + chartType) or a text block (type: "text", textContent).

Context-first rule: define the full dashboardContext before listing widgets. Widgets should contain only overrides — never duplicate what already lives in dashboardContext. If two or more widgets share the same period, groupBy, metric, currency, or filter scope, extract that shared value to dashboardContext first.

Temporary compatibility: the deprecated top-level context alias is accepted during migration, but always generate dashboardContext. Never send both.

When to Trigger

• Creating a new Costory dashboard
• Generating an interesting overview when the user has not specified every widget (use How to generate interesting dashboards below)
• Adding, replacing, or removing widgets on an existing dashboard
• Editing dashboardContext (global filter, period, groupBy, metric, currency) without recreating
• Copying a widget to another dashboard
• User asks for a cost overview "by service / by region" style dashboard

Dashboard dashboardContext fields

Each query still needs "type": "cost" (query kind — not inherited). What you omit on cost widgets is metricId, currency, groupBy, and period when they match dashboardContext.

Inheritance semantics

• Period, metricId, currency, groupBy: omit on widgets when they match dashboardContext.
• Similarity rule: when widgets or dashboards are very similar, identify the common datePreset/dates, groupBy, metricId, currency, and conditionsCel before writing widgets. Put common values in dashboardContext; widget fields are for exceptions only.
• groupBy: omit the field to inherit dashboardContext.groupBy; set groupBy: null to explicitly disable grouping for that widget.
• Period presets: if the user's range maps to an available DatePreset (for example TRAILING_30_DAYS, TRAILING_90_DAYS, LAST_MONTH, YTD), use dashboardContext.datePreset. Use startDate/endDate only for truly custom ranges.
• conditionsCel: inherited by default. Every cost widget AND-merges dashboard conditionsCel with its own filterCel.
• extendDashboardConditions: defaults to true (inherit dashboard filter). Set false only when the widget must ignore the dashboard filter entirely.
• Widget filterCel: widget-specific scope only — do not put the dashboard-wide filter here; put it in dashboardContext.conditionsCel.

Widget types

Two top-level widget kinds in create_dashboard / update_dashboard:

Chart widget — queries[].chartType

Set chartType on each series (cost / metric / usage / formula / budget / externalMetric). Omit → LINE. Primary series for sizing = first non-formula query (else first query).

Donut (composition for one period): there is no separate DONUT enum. Use chartType: "BAR" + widget aggBy: "Period" (and a groupBy). That is the product donut.

Time series vs period comparison

These are different modes — pick one per widget based on the question.

Enabling compare:

Prefer datePreset on the dashboard (or widget) + compare: {} for "vs previous period". Only pass compare.from/to for a custom other range.

{
  "title": "MoM by service",
  "queries": [{ "type": "cost", "name": "a", "chartType": "BAR", "groupBy": "cos_service_name" }],
  "aggBy": "Period",
  "compare": {}
}

Rules of thumb:

• Default to time series for overview dashboards and monitoring (spend over the last 30/90 days).
• Use comparison only when the insight is the change between two ranges, not the shape of a single range.
• Do not add compare just to show a BAR/LINE — that switches the widget into comparison mode.
• Donut (BAR + aggBy: "Period") is a single-period composition view, not a comparison and not a time series.
• Series chartType (queries[].chartType) and comparison compare.chartType are different enums — KPI_BREAKDOWN exists only on compare.chartType.

Text widgets

Notes, headings, or commentary — no queries, period, or dashboard inheritance.

{
  "type": "text",
  "title": "Notes",
  "textContent": "## AWS overview\nKey findings..."
}

Grid sizing (w / h / x / y)

Dashboard layout is a 12-column grid. Rows grow downward.

• w: width in columns (1–12)
• h: height in rows
• x / y: optional pin (0-based). On update_dashboard op: "add", supply both together or the widget is auto-packed at the end. Use values from get when copying a layout.

When to override size (set w/h explicitly):

Layout tips: omit w/h for a simple row of equal BAR/LINE charts (four 3×2). Prefer larger h for TABLE and multi-series AREA. Pin with x/y only when placing next to an existing widget or preserving a copied layout.

Supporting tools

How to generate interesting dashboards

Use when the user wants a useful FinOps overview but has not listed every widget — e.g. "build a dashboard for AWS", "something interesting for the platform team", "Kubernetes cost overview".

Do not ship a wall of identical "by service" BARs. Discover axes with tools, then mix composition, trend, comparison, usage (when scoped), and text widgets that explain the story.

Full playbook (layout recipe, anti-patterns, extended examples): call get_skill with skillId: "plugins/costory/skills/dashboards/references/how-to-generate-interesting-dashboards.md"

Discovery (required)

1. get_context — popular groupBys, recent dashboards, currency habits
2. Lock scope as CEL → this becomes dashboardContext.conditionsCel (provider, team, service, …)
3. suggest_groupby with period from/to matching the dashboard range + the same filterCel as that scope
   • Top hit → dashboardContext.groupBy when ≥2 widgets share it
   • Next 1–2 hits → secondary widget groupBy overrides
4. If scope is specific (not org-wide) → suggest_usage_metrics with that filterCel → optional usage / unit-economics widgets
5. Optionally query once so intro/findings text can cite real drivers (never invent numbers)
6. Draft dashboardContext first, then the widget palette below → create_dashboard

// suggest_groupby — same filterCel as dashboardContext.conditionsCel
{ "from": "2026-04-18", "to": "2026-07-17", "filterCel": "cos_provider in [\"AWS\"]" }

// suggest_usage_metrics — only with a narrow scope
{ "filterCel": "cos_service_name in [\"AmazonEKS\"]" }

Interesting widget palette

Build 5–8 widgets that answer different questions:

Text widgets turn charts into a story. Always include an intro; add findings when you inspected data. Put narrative in textContent, not stuffed into chart titles.

Layout sketch (12-col)

1. Intro text — 12 × 2
2. Composition 4 × 3 + Trend 8 × 3
3. Secondary split + table (or two bars) — 6 × 3 each
4. Period comparison — 12 × 3
5. Usage / unit economics if suggested — 6 × 3 each
6. Findings text — 12 × 2

Example — interesting AWS overview

{
  "name": "AWS interesting overview",
  "dashboardContext": {
    "conditionsCel": "cos_provider in [\"AWS\"]",
    "groupBy": "cos_service_name",
    "metricId": "cost",
    "currency": "USD",
    "datePreset": "TRAILING_90_DAYS"
  },
  "widgets": [
    {
      "type": "text",
      "title": "How to read this dashboard",
      "textContent": "## AWS cost overview\n\nTrailing 90 days. Default split: **service** (from suggest_groupby).\n\n1. **Composition** — share by service.\n2. **Weekly trend** — evolution of the same split.\n3. **MoM movers** — what changed vs the previous period.",
      "w": 12,
      "h": 2
    },
    {
      "title": "Spend composition by service",
      "queries": [{ "type": "cost", "name": "a", "chartType": "BAR" }],
      "aggBy": "Period",
      "w": 4,
      "h": 3
    },
    {
      "title": "Weekly trend by service",
      "queries": [{ "type": "cost", "name": "a", "chartType": "BAR" }],
      "aggBy": "Week",
      "w": 8,
      "h": 3
    },
    {
      "title": "By region",
      "queries": [{ "type": "cost", "name": "a", "chartType": "BAR", "groupBy": "cos_region" }],
      "aggBy": "Month",
      "w": 6,
      "h": 3
    },
    {
      "title": "Top services (table)",
      "queries": [{ "type": "cost", "name": "a", "chartType": "TABLE" }],
      "aggBy": "Period",
      "w": 6,
      "h": 3
    },
    {
      "title": "MoM movers by service",
      "queries": [{ "type": "cost", "name": "a", "chartType": "BAR" }],
      "aggBy": "Period",
      "compare": {},
      "w": 12,
      "h": 3
    },
    {
      "type": "text",
      "title": "What to watch",
      "textContent": "## Next checks\n\n1. Drill into the largest service and re-run suggest_groupby under that filter.\n2. For a narrow slice (e.g. EKS), call suggest_usage_metrics and add usage / cost-per-unit widgets.",
      "w": 12,
      "h": 2
    }
  ]
}

Workflow A — Create a new dashboard

1. get_skill with skillId: "dashboards" (this guide) — you are here
2. get_context + optional search / query to pick dimensions and validate CEL. If the widget list is open-ended, follow How to generate interesting dashboards (suggest_groupby, optional suggest_usage_metrics, text + mixed chart types)
3. Draft dashboardContext first:
   • metricId, currency, default groupBy when two or more widgets share the same split
   • Period: prefer datePreset (e.g. TRAILING_90_DAYS) when possible; otherwise use startDate + endDate
   • Global scope: conditionsCel when all widgets share a filter
4. List widgets as minimal overrides — each chart widget: title, queries (type, name, chartType, optional groupBy / filterCel), aggBy. Pick chartType + size from Widget types / Grid sizing above. Omit metricId, currency, period, groupBy, and conditionsCel when they match dashboardContext.
5. create_dashboard — include the returned URL in your reply

Example — AWS overview, by service and by region:

dashboardContext.metricId ≠ query "type". Both can be "cost" but mean different things:

• dashboardContext.metricId → which cost column to query (inherited — widgets omit metricId)
• queries[].type → query kind ("cost", "metric", "formula"…) — required on every query, not inherited

Widgets below do not repeat metricId, currency, period, groupBy, or conditionsCel from dashboardContext. Only "type": "cost" stays on each query.

{
  "name": "AWS Overview",
  "dashboardContext": {
    "conditionsCel": "cos_provider in [\"AWS\"]",
    "groupBy": "cos_service_name",
    "metricId": "cost",
    "currency": "USD",
    "datePreset": "TRAILING_90_DAYS"
  },
  "widgets": [
    {
      "title": "By Service",
      "queries": [{ "type": "cost", "name": "a", "chartType": "BAR" }],
      "aggBy": "Month"
    },
    {
      "title": "By Region",
      "queries": [{ "type": "cost", "name": "a", "chartType": "BAR", "groupBy": "cos_region" }],
      "aggBy": "Month"
    }
  ]
}

Workflow B — Extend an existing dashboard

1. search → dashboard id
2. get → read context and each widget's queryConfig
3. update_dashboard with op: "add" (or replace / remove) — new widgets omit fields that match the dashboard context, especially the period and common groupBy
4. Response includes inheritedContext — use it to know what widgets can omit
5. Include the returned URL in your reply

Example — add a region breakdown:

{
  "dashboardId": "clx9abc",
  "operations": [{
    "op": "add",
    "widget": {
      "title": "By Region",
      "queries": [{ "type": "cost", "name": "a", "chartType": "BAR", "groupBy": "cos_region" }],
      "aggBy": "Month"
    }
  }]
}

Workflow C — Copy a widget to another dashboard

1. get on the source dashboard → note x, y, w, h and the widget's effective query (resolved queryConfig)
2. get on the target dashboard → read its context
3. update_dashboard on the target with op: "add":
   • Pass x, y, w, h to preserve layout
   • Rebuild queries using overrides only relative to the target dashboard context — do not copy inherited metricId/currency/period/filter fields that the target already provides

Workflow D — Edit dashboard context

Change the shared context through the dashboardContext input (global filter, period, groupBy, metricId, currency, scopeId) without recreating the dashboard or rewriting widgets.

1. search → dashboard id (optional if already known)
2. get → read current context / conditionsCel
3. update_dashboard with a partial dashboardContext patch — omit fields you want to keep
4. Response includes updated inheritedContext; applied is [] when no widget ops were passed
5. Include the returned URL in your reply

Patch semantics:

Chart dashboards must keep a resolvable period after the merge — do not clear datePreset / dates if chart widgets remain.

Example — change the global filter only:

{
  "dashboardId": "clx9abc",
  "dashboardContext": {
    "conditionsCel": "cos_provider in [\"AWS\"]"
  }
}

Example — clear the global filter:

{
  "dashboardId": "clx9abc",
  "dashboardContext": {
    "conditionsCel": ""
  }
}

You can combine dashboardContext with operations in one call (new/replaced widgets inherit the merged context).

Per-widget overrides (complete catalog)

Chart widgets inherit dashboardContext for shared fields. Set a field on the widget (or query) only when it differs from dashboardContext. Text widgets ignore all of these (except title / description / layout).

Widget-level fields

Query-level fields (queries[])

Conditions inheritance (extendDashboardConditions + filterCel)

Dashboard filter = dashboardContext.conditionsCel. Widget-specific filter = query filterCel.

Examples (dashboard conditionsCel: cos_provider in ["AWS"]):

// Inherit AWS + narrow to EC2 (effective: AWS AND EC2)
{ "title": "EC2", "extendDashboardConditions": true,
  "queries": [{ "type": "cost", "name": "a", "chartType": "BAR",
    "filterCel": "cos_service_name in [\"AmazonEC2\"]" }], "aggBy": "Month" }

// Ignore dashboard AWS filter — show all providers for this widget
{ "title": "All clouds", "extendDashboardConditions": false,
  "queries": [{ "type": "cost", "name": "a", "chartType": "BAR" }], "aggBy": "Month" }

Do not repeat the dashboard-wide CEL inside every filterCel. Put shared scope in dashboardContext.conditionsCel; put exceptions in filterCel and/or extendDashboardConditions: false.

QUERY NAMING

name is a single letter (a, b, c) for formulas; put human labels in alias, never in name.

Safety Rules / Anti-patterns

• Do not repeat metricId, currency, groupBy, from/to, or datePreset on every widget when already in dashboardContext
• Do not use widget from/to for a common dashboard period when a dashboardContext.datePreset is possible
• Do not repeat the same groupBy across similar widgets instead of setting dashboardContext.groupBy
• Do not put the global scope (e.g. cos_provider in ["AWS"]) in each widget's filterCel instead of dashboardContext.conditionsCel
• Do not set extendDashboardConditions: true on every widget — omit it (default is inherit)
• Do not call create_dashboard without a period in dashboardContext — validation rejects it (chart widgets need a dashboard period; text widgets do not)
• Do not generate the deprecated context alias or send it together with dashboardContext
• Do not skip suggest_groupby on open-ended "interesting dashboard" requests and always default to cos_service_name
• Do not call suggest_usage_metrics without a specific filterCel
• Do not ship chart-only dashboards with no text intro / findings when generating an overview
• Do not invent findings numbers — only cite figures observed via query

Related Skills / Next Steps

• query — validate scope, inspect drivers before writing findings text, or explore usage / formulas
• reports — when the user wants a scheduled DIGEST or delivered report instead of (or in addition to) a live dashboard
• virtual-dimensions — when the desired groupBy axis does not exist yet and must be built as a custom cost axis