Chart input

create_chart, update_chart and get_live_chart_embed take the same chart input, except size, which only create_chart takes. Only chart_type is required by the schema. Every type except gantt and custom also needs table. Send numbers already scaled to the unit, such as 41.2 with "unit": "EUR m", not 41200000.

{
  "chart_type": "clusteredBar",
  "table": {
    "categories": ["2021", "2022", "2023", "2024", "2025"],
    "series": [{ "name": "Online sales" }],
    "values": [[41.2, 48.9, 57.3, 66.0, 78.4]]
  },
  "unit": "EUR m"
}

Chart types

For horizontal bars, send stackedBar, stackedBar100, clusteredBar or waterfall with "orientation": "horizontal". A single-series horizontal bar chart is a stackedBar with one series.

Fields

Data

Units

Callouts and focus

Layout and style

Text

Charts have no title, subtitle or footnote unless you send one. On a slide, the slide title usually carries the message and the source sits in a footnote outside the chart.

Table shapes

The table is the same object for every native type except gantt. What the series and categories mean depends on the type, as the chart types table shows. A few near-miss shapes are accepted and converted.

• A list of rows with a header row, where the first column holds the categories.
• Series given as plain strings, or with their own values array.
• Numeric categories, which become strings.
• For a single series, values as a flat list.

[
  ["", "Revenue", "Cost"],
  ["2023", 10, 6],
  ["2024", 12, 7]
]

Waterfall totals

In a waterfall, each value is a step up or down. A cell set to "total" draws a bar from the axis to the running sum of every category before it. Give the first category its real starting value; a "total" there has nothing to sum.

{
  "chart_type": "waterfall",
  "table": {
    "categories": ["2024", "Price", "Volume", "Mix", "FX", "2025"],
    "series": [{ "name": "Revenue" }],
    "values": [[120, 8.5, 6.2, -2.1, -3.4, "total"]]
  },
  "unit": "EUR m"
}

Annotations

annotations is a list of callouts, each with a kind: delta, cagr, refLine, band, level, axisBreak. Anchored kinds point at a bar or point by index.

An anchor is an object with a category_index and an optional series_index, both 0-based. Without series_index it points at the stack total. On stacked and waterfall charts, a delta or CAGR with series_index measures that series' own values. On clustered bars, lines and scatter, it anchors to that one series.

[{ "kind": "cagr", "from": { "category_index": 0 }, "to": { "category_index": 4 } }]

delta

cagr

Compound annual growth between two anchors. Only for yearly categories such as 2021 or FY24; use a delta for months or quarters.

refLine

A horizontal line at a target, average or threshold.

band

A value range drawn as two reference lines with one label.

level

A bracket between two anchors.

axisBreak

Breaks the value axis so one large bar stops flattening the rest. Use it when the largest value is more than about four times the next. Leave out from and to to cut the largest gap between bars automatically; give both to choose the hidden range. One per chart, and not on donut, mekko or Harvey ball charts.

{
  "chart_type": "clusteredBar",
  "table": {
    "categories": ["Instagram", "TikTok", "YouTube", "Pinterest", "Snapchat"],
    "series": [{ "name": "Mentions" }],
    "values": [[1840, 312, 268, 141, 96]]
  },
  "unit": "k",
  "annotations": [{ "kind": "axisBreak" }],
  "highlight": { "categories": ["TikTok"] }
}

Automatic callouts

When annotations is left out of create_chart, ChartKit adds at most one callout and one axis break, and the result text says which. They are stored with the chart, so update_chart keeps them until you send new annotations.

Gantt charts

Send gantt instead of table. Dates are ISO, such as "2026-01-05", or natural language, such as "5 Jan 2026" or "Q1 2026". annotations, highlight, sort, unit and orientation do not apply.

{
  "chart_type": "gantt",
  "gantt": {
    "activities": [
      { "name": "Data collection", "start": "2026-01-05", "end": "2026-02-13", "progress": 100 },
      { "name": "Social listening", "start": "2026-02-02", "end": "2026-03-20", "progress": 40 },
      { "name": "Client workshop", "milestone": "2026-03-26" },
      { "name": "Final report", "start": "2026-03-23", "end": "2026-04-17", "planned": true }
    ],
    "shades": [{ "from": "2026-04-06", "to": "2026-04-10", "label": "Easter" }],
    "dateLines": [{ "date": "today", "label": "Today" }]
  }
}

A table also works as a fallback: one series per activity and the categories Start, End and Milestone, with date strings or "" in the cells.

Custom charts

chart_type: "custom" draws a Vega-Lite v5 spec in ChartKit's styling, for charts no native type covers. Prefer a native type when one fits; native charts stay editable in the ChartKit editor and support annotations and label control.

• The data is always { "name": "table" }. Without records, the table is read in long form with the fields category, series and value.
• With records, each row is one category: key names the category field, and fields lists the other columns by id. Compute derived columns into the rows, because the spec cannot calculate.
• No width, height or title in the spec, no calculate transforms and no expressions. Colours come from { "scheme": "chartkit" } or the tokens ck:1 to ck:8, ck:muted, ck:ink, ck:pos and ck:neg.
• A spec that ChartKit rejects returns the errors in the message, so you can fix it and call again.

Limits

• The stored chart model and the stored input can each be up to 512 KB of JSON.
• One axisBreak per chart.
• Harvey ball values must be between 0 and 100. Waterfall is the only type that accepts "total" cells.