Build chart segments and values

Manual charts are built from segments and values. A ChartSegment holds a Formula — display text/HTML that references value identifiers — plus a title and color. Each ChartSegmentValue is a named, workspace-scoped aggregation: a ChartSegmentValueFunctions rollup (COUNT, SUM, AVERAGE, …) over one workspace’s records, optionally narrowed to a single custom field and filtered with a TodoFilterInput. The formula combines those values into the number the chart renders.

These mutations apply only to manual charts — charts you created with inline chartSegments. A chart built from metadata.barChart or metadata.pieChart is auto-generated: its values come from an axis spec, not from segments, so the segment and value mutations do not apply to it. See Create and manage charts for the manual-vs-auto distinction.

Every mutation on this page republishes the parent chart to dashboard subscribers and enqueues a recalculation. Results arrive asynchronously over subscribeToChart — not in the mutation response. Workspaces are Project objects and records are Todo objects in the API.

The UID linkage

The non-obvious core mechanic: each ChartSegmentValue has a stable uid, and the segment’s formula.logic.text and formula.logic.html reference those uid tokens. The formula is the expression; the values are its variables. When you copy a chart with copyChart, Blue regenerates each value uid and string-replaces it inside the copied formula so the link survives.

Pass uid explicitly on a value when you want the formula to reference a known token; omit it and Blue auto-generates one. The same applies to a segment’s own uid.

Segments

Create a segment

Use the createChartSegment mutation to add a segment to a manual chart. Provide the chart, a title, a color, the formula, and (optionally) the segment’s chartSegmentValues inline.

Request

mutation CreateChartSegment {
  createChartSegment(
    input: {
      chartId: "chart_123"
      title: "Win rate"
      color: "#2563eb"
      formula: {
        logic: {
          text: "{{value_won}} / {{value_total}}"
          html: "<p>{{value_won}} / {{value_total}}</p>"
        }
        display: { type: PERCENTAGE, precision: 1 }
      }
      chartSegmentValues: [
        { uid: "value_won", title: "Won deals", projectId: "project_123", function: COUNT }
        { uid: "value_total", title: "All deals", projectId: "project_123", function: COUNT }
      ]
    }
  ) {
    id
    uid
    title
    color
    chartSegmentValues {
      id
      uid
      title
    }
  }
}

Parameters

CreateChartSegmentInput

FormulaInput

FormulaLogicInput

FormulaDisplayInput

ChartSegmentValueInput

Response

{
  "data": {
    "createChartSegment": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "uid": "seg_a1b2c3",
      "title": "Win rate",
      "color": "#2563eb",
      "chartSegmentValues": [
        { "id": "clm4n8qwx000108l0h7yzerm2", "uid": "value_won", "title": "Won deals" },
        { "id": "clm4n8qwx000208l0k9pqwst3", "uid": "value_total", "title": "All deals" }
      ]
    }
  }
}

ChartSegment

Edit a segment

Use the editChartSegment mutation to change a segment’s title, color, or formula. Only the fields you pass are updated; the rest are left unchanged. Passing a new formula triggers a recalculation; changing only the title or color republishes the chart without recomputing.

Request

mutation EditChartSegment {
  editChartSegment(
    input: {
      id: "segment_123"
      title: "Win rate (rounded)"
      formula: {
        logic: {
          text: "{{value_won}} / {{value_total}}"
          html: "<p>{{value_won}} / {{value_total}}</p>"
        }
        display: { type: PERCENTAGE, precision: 0 }
      }
    }
  ) {
    id
    title
    formula {
      display {
        type
        precision
      }
    }
  }
}

Parameters

EditChartSegmentInput

The response is the updated ChartSegment (same shape as createChartSegment above).

Delete a segment

Use the deleteChartSegment mutation to remove a segment and its values from the chart. The chart is republished to dashboard subscribers.

Request

mutation DeleteChartSegment {
  deleteChartSegment(id: "segment_123") {
    success
  }
}

deleteChartSegment returns a MutationResult, which exposes only success and operationId. It does not take a sub-selection on a segment object.

Response

{
  "data": {
    "deleteChartSegment": {
      "success": true
    }
  }
}

MutationResult

Values

You can manage values inline on a segment (above) or independently with the value mutations below.

Create a value

Use the createChartSegmentValue mutation to add a value to an existing segment. The new value’s uid is what you reference from the segment’s formula.

Request

mutation CreateChartSegmentValue {
  createChartSegmentValue(
    input: {
      chartSegmentId: "segment_123"
      uid: "value_won"
      title: "Won deals"
      projectId: "project_123"
      customFieldId: "field_123"
      function: SUM
      filter: { showCompleted: false, todoListIds: ["list_123"] }
    }
  ) {
    id
    uid
    title
    projectId
    customFieldId
    function
  }
}

Parameters

CreateChartSegmentValueInput

ChartSegmentValueFunctions

Response

{
  "data": {
    "createChartSegmentValue": {
      "id": "clm4n8qwx000308l0v2bcdef4",
      "uid": "value_won",
      "title": "Won deals",
      "projectId": "clm4n8qwx000408l0p5ghij5k",
      "customFieldId": "clm4n8qwx000508l0q6klmn6l",
      "function": "SUM"
    }
  }
}

ChartSegmentValue

Edit a value

Use the editChartSegmentValue mutation to change a value’s title, workspace, custom field, function, or filter. Only the fields you pass are updated. Editing a value always recalculates the chart.

If you pass customFieldId, it is validated against the new projectId when you also pass one — otherwise against the value’s existing workspace.

Request

mutation EditChartSegmentValue {
  editChartSegmentValue(
    input: { id: "value_123", function: AVERAGE, filter: { dueStart: "2026-01-01T00:00:00.000Z" } }
  ) {
    id
    title
    function
  }
}

Parameters

EditChartSegmentValueInput

The response is the updated ChartSegmentValue (same shape as createChartSegmentValue above).

Delete a value

Use the deleteChartSegmentValue mutation to remove a value. The chart is republished and recalculated.

Request

mutation DeleteChartSegmentValue {
  deleteChartSegmentValue(id: "value_123") {
    success
  }
}

deleteChartSegmentValue returns a MutationResult — select success and/or operationId, with no sub-selection on a value object.

Response

{
  "data": {
    "deleteChartSegmentValue": {
      "success": true
    }
  }
}

Errors

Permissions

Segments and values are governed by the parent chart’s dashboard. Every mutation here requires that you either created the dashboard or are a DashboardUser on it with the EDITOR role. A VIEWER (or anyone without dashboard access) is rejected with the corresponding not-found error — the API does not distinguish “doesn’t exist” from “you can’t see it” for these resources.

Beyond dashboard access, creating or editing a value also checks the data it points at: you must be a member of every referenced projectId, and any customFieldId must belong to that workspace. This prevents a value from aggregating records you can’t otherwise access.

Related

• Charts — overview of charts and how they live on a dashboard.
• Create and manage charts — create a manual or auto-generated chart, then copyChart (which remaps value uids in formulas).
• Preview, recalculate, and export charts — preview a chart before saving and force recalculation.
• Query and subscribe to charts — read chart results and subscribe for recalculation updates.
• List records — the TodoFilterInput fields used by a value’s filter.