Dashboards API

Manage custom dashboards and tiles programmatically.

Service: DashboardsService
Auth: JWT + x-project-id

Operations

Method	Description
`List`	List all dashboards in a project
`Get`	Get a dashboard with all tiles
`Create`	Create a new dashboard
`Update`	Update dashboard metadata (name, etc.)
`Upsert`	Replace all tiles (full reconcile)
`Delete`	Delete a dashboard

List dashboards


// Response
{
  "dashboards": [
    {
      "id": "dash_abc123",
      "name": "Growth KPIs",
      "createdAt": "2026-01-15T10:00:00Z",
      "updatedAt": "2026-06-01T14:00:00Z"
    }
  ]
}

Get dashboard


// Request
{ "id": "dash_abc123" }
 
// Response
{
  "dashboard": {
    "id": "dash_abc123",
    "name": "Growth KPIs",
    "tiles": [ ... ]
  }
}

Upsert tiles

Tile changes use a full-reconcile upsert — send the complete desired tile array. There are no individual tile create/update/delete RPCs.


{
  "dashboardId": "dash_abc123",
  "tiles": [
    {
      "id": "tile_001",
      "type": "TILE_TYPE_INSIGHT",
      "position": { "x": 0, "y": 0, "w": 6, "h": 4 },
      "insight": {
        "query": {
          "events": [{ "name": "page_view" }],
          "granularity": "GRANULARITY_DAY",
          "aggregation": "AGGREGATION_UNIQUE_USERS"
        },
        "visualization": "VISUALIZATION_LINE"
      }
    },
    {
      "id": "tile_002",
      "type": "TILE_TYPE_MARKDOWN",
      "position": { "x": 6, "y": 0, "w": 6, "h": 2 },
      "markdown": {
        "content": "# Weekly Goals\n\n- Hit 10k DAU\n- Launch referral program"
      }
    }
  ]
}

The saved payload is the source of truth. Omitting a tile ID from the array deletes that tile.

Tile types

Type	Field	Description
`TILE_TYPE_INSIGHT`	`insight`	Chart or KPI bound to an `InsightQuerySpec`
`TILE_TYPE_MARKDOWN`	`markdown`	Free-form markdown content

Insight tiles use the same query spec as InsightsService. See Insights API for query spec fields.

TypeScript client


import { DashboardsService } from './gen/dashboards/v1/dashboards_connect'
 
const client = createClient(DashboardsService, jwtTransport)
 
// Create dashboard
const { dashboard } = await client.create({
  name: 'Growth KPIs'
})
 
// Add tiles
await client.upsert({
  dashboardId: dashboard.id,
  tiles: [
    {
      type: 'TILE_TYPE_INSIGHT',
      position: { x: 0, y: 0, w: 12, h: 4 },
      insight: {
        query: {
          events: [{ name: 'signup' }],
          granularity: 'GRANULARITY_DAY',
          aggregation: 'AGGREGATION_COUNT'
        },
        visualization: 'VISUALIZATION_LINE'
      }
    }
  ]
})

Dashboard UI

The visual editor is the easiest way to build dashboards. Use the API for:

Provisioning default dashboards for new projects
CI/CD dashboard templates
Syncing dashboards across environments

See Dashboards for the UI workflow.