Query and subscribe to charts

Use the chart query to read a single chart by id, the charts query to list every chart on a dashboard, and the subscribeToChart subscription to receive real-time create, update, and delete events. Charts are Chart objects in the API; they always live inside a parent dashboard (a Dashboard object), so reads are scoped by the chart’s dashboard, not by an organization or workspace.

A chart is one of three card types — STAT, PIE, or BAR. Manual charts carry chartSegments (each a Formula over named ChartSegmentValue aggregates); auto-generated charts instead carry metadata describing a bar or pie spec over records. Both shapes come back from these queries; see Build chart segments and values and Create and manage charts for how each is constructed.

Query a single chart

Use the chart query to fetch one chart by its id.

Request

query GetChart {
  chart(id: "chart_123") {
    id
    title
    type
    position
    isCalculating
    needCalculation
    chartSegments {
      id
      uid
      title
      color
      formulaResult
    }
    createdAt
    updatedAt
  }
}

Parameters

Response

{
  "data": {
    "chart": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "title": "Revenue by stage",
      "type": "STAT",
      "position": 1024,
      "isCalculating": false,
      "needCalculation": false,
      "chartSegments": [
        {
          "id": "clm4n8qwx000108l0a1b2c3d4",
          "uid": "seg_a1b2c3",
          "title": "Closed won",
          "color": "#2563eb",
          "formulaResult": 48250
        }
      ],
      "createdAt": "2026-04-12T09:30:00.000Z",
      "updatedAt": "2026-05-28T14:05:11.000Z"
    }
  }
}

List charts on a dashboard

Use the charts query to list every chart on a dashboard. The filter requires a dashboardId — there is no organization- or workspace-level chart listing. Results are paginated with offset-based skip/take and ordered by sort (default [position_ASC], the card order on the dashboard).

Request

The smallest valid call passes a filter with the required dashboardId:

query ListCharts {
  charts(filter: { dashboardId: "dashboard_123" }) {
    items {
      id
      title
      type
      position
      isCalculating
      needCalculation
    }
    pageInfo {
      totalItems
      totalPages
      page
      perPage
      hasNextPage
      hasPreviousPage
    }
  }
}

Parameters

ChartFilterInput

ChartSort

sort takes an array of these enum values; later values break ties from earlier ones.

Response

{
  "data": {
    "charts": {
      "items": [
        {
          "id": "clm4n8qwx000008l0g4oxdqn7",
          "title": "Revenue by stage",
          "type": "STAT",
          "position": 1024,
          "isCalculating": false,
          "needCalculation": false
        },
        {
          "id": "clm4n8qwx000208l0e5f6g7h8",
          "title": "Records by list",
          "type": "BAR",
          "position": 2048,
          "isCalculating": false,
          "needCalculation": false
        }
      ],
      "pageInfo": {
        "totalItems": 2,
        "totalPages": 1,
        "page": 1,
        "perPage": 20,
        "hasNextPage": false,
        "hasPreviousPage": false
      }
    }
  }
}

Filtered listing

Pass a todoFilter to recompute the dashboard’s charts against an ad-hoc record filter — for example, only records updated this quarter:

query ListChartsFiltered {
  charts(
    filter: {
      dashboardId: "dashboard_123"
      todoFilter: { projectIds: ["project_123"], showCompleted: false }
    }
    sort: [position_ASC]
    take: 50
  ) {
    items {
      id
      title
      type
      isCalculatingWithFilter
    }
    pageInfo {
      totalItems
      hasNextPage
    }
  }
}

todoFilter is a TodoFilterInput — the same record-filter shape used across the API. See List records for its full field set.

Subscribe to chart changes

Use the subscribeToChart subscription to receive real-time events when charts on a dashboard are created, updated, or deleted — including the recomputed values that follow a recalculation. Subscriptions run over the WebSocket transport at wss://api.blue.cc/graphql.

Request

subscription OnChartChange {
  subscribeToChart(filter: { dashboardId: "dashboard_123" }) {
    mutation
    node {
      id
      title
      type
      position
      isCalculating
      needCalculation
      chartSegments {
        id
        uid
        formulaResult
      }
    }
    previousValues {
      id
      title
    }
  }
}

Parameters

SubscribeToChartFilterInput

Event payload

Each event delivers a ChartSubscriptionPayload.

Example event

{
  "data": {
    "subscribeToChart": {
      "mutation": "UPDATED",
      "node": {
        "id": "clm4n8qwx000008l0g4oxdqn7",
        "title": "Revenue by stage",
        "type": "STAT",
        "position": 1024,
        "isCalculating": false,
        "needCalculation": false,
        "chartSegments": [
          {
            "id": "clm4n8qwx000108l0a1b2c3d4",
            "uid": "seg_a1b2c3",
            "formulaResult": 48250
          }
        ]
      },
      "previousValues": null
    }
  }
}

Return types

Chart

ChartSegment

ChartSegmentValue

ChartMetadata

metadata is a union — ChartMetadataBarChart for BAR charts and ChartMetadataPieChart for PIE charts — so select fields through an inline fragment:

query GetChartMetadata {
  chart(id: "chart_123") {
    id
    type
    metadata {
      ... on ChartMetadataBarChart {
        barChart {
          xAxis {
            title
            type
            interval
          }
          yAxis {
            title
            function
          }
        }
      }
      ... on ChartMetadataPieChart {
        pieChart {
          groupBy {
            title
            type
          }
          value {
            title
            function
          }
        }
      }
    }
  }
}

For BAR, barChart.xAxis carries the grouping (type is a BarChartXAxisType, with an optional interval for date axes) and barChart.yAxis carries the aggregate (function is a ChartSegmentValueFunctions). For PIE, pieChart.groupBy and pieChart.value mirror those roles. The axis input shapes are documented in Create and manage charts.

PageInfo

PageInfo also exposes startCursor and endCursor, but both are deprecated — charts are not cursor-paginated. Walk pages with skip/take.

Errors

Permissions

You must be authenticated. Charts inherit their access from the parent dashboard: you can read a dashboard’s charts if you created the dashboard or have been added to it as a DashboardUser (any role — VIEWER is sufficient for reads). The subscribeToChart stream applies the same check and silently drops events for dashboards you can’t access. Writing charts requires the dashboard owner or the EDITOR role — see Create and manage charts.

Related

• Charts overview — How charts, segments, values, and metadata fit together.
• Create and manage charts — Create, edit, copy, and delete charts.
• Build chart segments and values — Construct the manual building blocks.
• Preview, recalculate, and export charts — Compute results and export CSVs.
• List dashboards — Find the dashboards whose charts you can query.