Skip to main content

Building Dashboards

This guide builds a dashboard from scratch: create it, have an agent add tiles, arrange them, connect them to live data, then organise and share it. For what dashboards are and how they behave, see Dashboards.

Before you start​

  • To have an agent build tiles, you need an agent with the dashboard functions assigned (create_dashboard, list_element_types, add_dashboard_element, update_dashboard_element, move_dashboard_element, replace_dashboard_layout, remove_dashboard_element, list_dashboard_elements). See Adding Tools to Agents.
  • For tiles that stay current by themselves, create the data sources first, scoped to the project if the dashboard will be shared. See Creating Data Sources.

Step 1: Create the dashboard​

  1. Go to Dashboard.
  2. Choose New in the header (or New dashboard in the dashboard picker or the library). If you have no dashboards yet, choose Create Dashboard (shown as Create Dashboard manually when a builder agent is offered).
  3. Enter a Name, and optionally a Group (for example Operations) and a Description.
  4. Choose Create dashboard.

The new dashboard opens, empty.

Step 2: Ask an agent to add tiles​

Open a chat with your agent and describe the tiles you want, naming the dashboard. Be specific about what each tile shows and where its data comes from. For example:

On my "Operations" dashboard, add a table of this week's open support tickets from the "Support tickets" data source showing subject, customer and age, a metric card with the count, and a markdown note explaining what the dashboard is for.

A capable agent will:

  1. call list_element_types to see which element types and library templates exist and what data each expects;
  2. read any data it needs, for example with read_data_source;
  3. add each tile with add_dashboard_element, choosing a width (full, two_thirds, half, third or quarter) and letting the platform place it in the first free slot.

Data an agent writes into a tile is a snapshot. Ask the agent to refresh it when you want it updated, or bind the tile to a data source so it stays current by itself (Step 4).

Tiles appear on the open dashboard as the agent adds them; you do not need to reload. When an agent updates a tile, the tile shows via and the agent's name in its title bar.

You can also ask for changes later: "make the token tile a third of the width", "replace the table with a bar chart of PRs per repository", "remove the markdown note".

tip

If the agent asks for a library template by name (such as a KPI row or donut chart), the platform resolves it from the element library and fills in the template's code, so the agent only supplies the data. Your own templates can be added to the library too; see Creating Custom Dashboard Elements.

Step 3: Arrange the grid​

  • Drag a tile by its title to move it.
  • Drag a tile's corner to resize it. This pins its height.
  • To let a tile size itself to its content again, open Configure element (the gear) and turn on Fit height to content.
  • If uneven heights make a row look ragged, open Dashboard actions → Edit details and turn on Align rows.

Your layout is saved as you go. For a full rearrangement, asking the agent ("put the three metric cards in one row across the top") produces a single, tidy update.

Step 4: Connect live data​

Tiles that are bound to a data source update whenever the source refreshes. The in-platform dashboard functions write data but do not bind tiles, so binding is done through the platform API or the platform MCP server's dashboard tools (for example from Claude Code); see Binding Data Sources to Dashboard Elements.

Use the refresh button in the dashboard header to pull fresh data from every source feeding the dashboard, or Refresh data on a single tile.

If a tile shows a marker such as Not live or Never loaded, hover over it for the reason and the fix.

Step 5: Organise, pin and share​

From Dashboard actions (⋮) in the header, or a card's menu in Browse all:

  • Edit details to change the name, group or description.
  • Pin to quick access to put it on your pinned strip. Drag the chips to put them in the order you want.
  • Share with team to let everyone in your organisation see it. You are asked to confirm.
  • Hide to take a dashboard out of your lists without deleting it.

In Browse all, use a group's menu to Rename group… for every dashboard in it at once, or Ungroup these dashboards.

Building through the API​

Developers can build the same thing with the platform API or the platform MCP server:

POST /dashboards
{ "name": "Operations", "group_name": "Ops", "description": "Daily health at a glance" }
POST /dashboards/{dashboard_id}/elements
{
  "element_type": "metric_card",
  "title": "Tokens (30 days)",
  "size": "third",
  "data": { "value": 0, "label": "Total tokens" },
  "data_source": {
    "type": "data_source",
    "data_source_id": 42,
    "query_params": { "period": "30d" },
    "mapping": { "value": "$.rows[0].total_tokens", "label": "Total tokens" }
  }
}

Leave out grid_x and grid_y to auto-place the tile, or give both. x plus width must fit within 12 columns. PUT /dashboards/{dashboard_id}/layout replaces every tile's position at once.