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.query). 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

One shape for every chart. Supply query for an auto-generated chart; omit it for a manual one, whose numbers come from its chartSegments instead.

ChartQueryInput:

ChartDimensionInput:

Bucket order and limit

ChartOrderInput decides the order the buckets are drawn in. Ordering happens after every measure has been computed, not in the aggregate, so a chart with several metrics keeps one bucket order.

Two orders are refused with BAD_USER_INPUT:

• FIELD unless the dimension type is TODO. Only a record axis has exactly one value per bucket to sort on.
• LABEL on a dimension that buckets by date (TODO_DUE_DATE, TODO_CREATED_AT, TODO_UPDATED_AT, TODO_COMPLETED_AT, or a DATE custom field). Those labels are formatted dates, so an alphabetical sort would put Apr 2026 before Jan 2026.

limit needs a resolvable order to decide which buckets stay — either an explicit order, or the display type’s own default. A leaderboard ranks by VALUE DESC on its own, so it accepts a limit without an order; a funnel takes no order at all and so takes no limit. A limit with no resolvable order, or outside 1–200, is refused with BAD_USER_INPUT.

The limit is a display concern: the aggregate still computes and stores every bucket, and exports still cover every record the chart counted. Read the value back from limit on the ChartDimension output type.

ChartMetricInput:

ChartPresentationInput carries stackMode, target, direction, bands and context. None of it affects which records the chart covers.

Stacked bar charts

A BAR chart can add a second grouping dimension so each bucket is split into stacked slices — records per assignee within each workspace, for example. Set breakout on ChartQueryInput to turn this on, and presentation.stackMode to choose how the slices combine.

ChartBreakoutInput mirrors the dimension input, minus interval — bucketing a date axis by another date is not a composition:

ChartStackMode is either STACKED (slices are stacked and the bar’s height is the bucket total) or PERCENT (each bucket is normalised to 100%, so only the mix is shown). A breakdown always stacks; side-by-side grouped bars are not offered.

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: {
        query: {
          dimensions: [{ title: "Workspace", type: PROJECT }]
          metrics: [{ title: "Records" }]
        }
      }
    }
  ) {
    id
    title
    type
    displayType
    metadata {
      query {
        dimensions {
          title
          type
        }
        metrics {
          key
          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.