Create and manage charts

A chart is a single card on a dashboard. This page covers the full lifecycle: create a chart with createChart, change its title, position, display, or metadata with editChart, duplicate it into the same or another dashboard with copyChart, and remove it with deleteChart. Charts are Chart objects in the API.

Every chart is either a manual chart (driven by chartSegments — formulas over project-scoped values) or an auto-generated chart (driven by metadata.barChart or metadata.pieChart). createChart accepts either shape; the segment and value mutations apply only to manual charts. See the section overview for the full type map.

createChart

Use the createChart mutation to add a chart to a dashboard.

Request

The smallest call creates an empty STAT chart. You build out its segments afterward with createChartSegment.

mutation CreateChart {
  createChart(input: { dashboardId: "dashboard_123", title: "Open records", type: STAT }) {
    id
    title
    type
    position
    isCalculating
    needCalculation
  }
}

Parameters

CreateChartInput

ChartType

FormulaDisplayInput

ChartMetadataInput

Supply exactly one of barChart or pieChart for an auto-generated chart.

BarChartMetadataInput is { xAxis: BarChartXAxisInput!, yAxis: BarChartYAxisInput! }; PieChartMetadataInput is { groupBy: PieChartGroupByInput!, value: PieChartValueInput! }. The axis inputs share a common shape:

For chartSegments (manual charts), the segment and value input fields are documented on Build chart segments and values; the example below shows the inline form.

Response

{
  "data": {
    "createChart": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "title": "Open records",
      "type": "STAT",
      "position": 65535,
      "isCalculating": true,
      "needCalculation": true
    }
  }
}

Returns

createChart returns the new Chart.

Full example

Create an auto-generated BAR chart that counts records by workspace, formatted as a whole number.

mutation CreateBarChart {
  createChart(
    input: {
      dashboardId: "dashboard_123"
      title: "Records per workspace"
      type: BAR
      display: { type: NUMBER, precision: 0 }
      metadata: {
        barChart: {
          xAxis: { title: "Workspace", type: PROJECT }
          yAxis: { title: "Records", function: COUNT }
        }
      }
    }
  ) {
    id
    title
    type
    metadata {
      ... on ChartMetadataBarChart {
        barChart {
          xAxis {
            title
            type
          }
          yAxis {
            title
            function
          }
        }
      }
    }
    needCalculation
  }
}

To create a manual chart instead, pass chartSegments (and omit metadata). Each segment carries a formula whose logic.text/logic.html reference its values by their uid:

mutation CreateManualChart {
  createChart(
    input: {
      dashboardId: "dashboard_123"
      title: "Won vs. lost"
      type: PIE
      chartSegments: [
        {
          title: "Won deals"
          color: "#22c55e"
          uid: "seg_won"
          formula: {
            logic: { text: "val_won", html: "<span>val_won</span>" }
            display: { type: NUMBER }
          }
          chartSegmentValues: [
            { uid: "val_won", title: "Won", projectId: "project_123", function: COUNT }
          ]
        }
      ]
    }
  ) {
    id
    title
    chartSegments {
      id
      uid
      title
    }
  }
}

Errors

{
  "errors": [
    {
      "message": "Dashboard was not found.",
      "extensions": { "code": "DASHBOARD_NOT_FOUND" }
    }
  ]
}

editChart

Use the editChart mutation to rename, reposition, restyle, or re-spec a chart. Only the fields you pass are changed; omitted fields are left untouched. Segments and values are not edited here — use the segment and value mutations.

Request

mutation EditChart {
  editChart(input: { id: "chart_123", title: "Open records (this quarter)" }) {
    id
    title
    updatedAt
  }
}

Parameters

EditChartInput

Response

{
  "data": {
    "editChart": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "title": "Open records (this quarter)",
      "updatedAt": "2026-05-29T14:07:42.000Z"
    }
  }
}

editChart returns the updated Chart (same shape as createChart).

Errors

copyChart

Use the copyChart mutation to duplicate a chart into the same dashboard or a different one. The copy is a deep copy: segments, values, formulas, type, display, and metadata are recreated with fresh identifiers.

Request

mutation CopyChart {
  copyChart(input: { chartId: "chart_123", dashboardId: "dashboard_456" }) {
    id
    title
    type
    position
  }
}

Parameters

CopyChartInput

Response

{
  "data": {
    "copyChart": {
      "id": "clm4n8qwx000409l0d1weq2bk",
      "title": "Open records",
      "type": "STAT",
      "position": 131070
    }
  }
}

copyChart returns the newly created Chart.

The copy is appended after the last chart in the destination dashboard (see Position defaults) and its results are recalculated asynchronously, so it briefly reports needCalculation: true.

Errors

deleteChart

Use the deleteChart mutation to remove a chart and its segments. deleteChart takes the chart id directly, not an input object.

Request

mutation DeleteChart {
  deleteChart(id: "chart_123") {
    success
  }
}

Parameters

Response

deleteChart returns a MutationResult. It exposes only success and operationId — there is no message field.

{
  "data": {
    "deleteChart": {
      "success": true
    }
  }
}

MutationResult

Errors

If the chart is found but the delete itself fails, the mutation returns { "success": false } rather than throwing.

ChartFunction vs. ChartSegmentValueFunctions

Two enums share the same seven members but live in different places — keep them straight in examples:

Position defaults

position is a Float! controlling order within the dashboard. When you omit position on createChart (and always on copyChart), the server appends the chart after the current last one: it takes the highest existing position and adds a fixed gap, or uses that gap as the starting position if the dashboard has no charts yet. Pass an explicit position to slot a chart between two others. Reorder later with editChart.

Permissions

All four mutations are writes and require the caller to either have created the chart’s dashboard or hold the EDITOR role on it. copyChart checks this on both the source chart’s dashboard and the destination dashboard.

A caller without sufficient access receives CHART_NOT_FOUND (or DASHBOARD_NOT_FOUND for the dashboard argument) rather than a distinct permission error — the chart or dashboard simply does not match the access-scoped lookup. Reads, by contrast, require only viewer access; see Query and subscribe to charts.

Related

• Charts — section overview and the full chart type map.
• Build chart segments and values — add the formulas and aggregations that power a manual chart.
• Preview, recalculate, and export — preview before saving, force a recompute, or export to CSV.
• Query and subscribe to charts — read charts and listen for real-time updates.
• Dashboards — charts always belong to a dashboard; access is inherited from it.