Update Analytics Panel

Set what a panel shows: its sources and their SQL, the transform, the display type and its settings, columns, formats, click wiring and its place on the grid. Send only what changes.

PUT

Path

Path parameters

stringrequired

The page id, from List Analytics Pages.

stringrequired

The panel id, from Get Analytics Page or Create Analytics Panel.

Headers

Optional headers

stringrequired

Required. The revision you last read: the revision from its read (Get Workflow Definition for a workflow, Get Analytics Page Definition for an Analytics page, Get Analytics Data Source Table for a fixed source's table), or meta.revision from your last change to it. The ETag header of either answer is the same value, ready to send back. The change applies only if nobody changed it since: otherwise it answers 412 with the current revision in error.details.revision. Send it as a strong entity tag ("r_..."): a weak one (W/"...") never matches and answers 412. Without it the request answers 428.

string

Optional. The id of the organization to act in. Leave it out to act in the API key's own organization. Here a key acts in another organization only as one of its members: with "Use this key across all of your organizations" on, in an organization its creator belongs to with a role. Child organizations and MindCloud staff access do not reach this endpoint. Every response's X-Company-Id header names the organization it acted in. See Organizations.

Body

Arguments

string

The panel's title.

The panel's title. Setting it turns off automatic renaming for this panel.

string

The subhead of its drill-down view.

The line under the title when the panel opens as a full-page drill-down view. An empty string clears it.

string

page or drill.

page puts the panel on the grid; drill takes it off the grid, to open when another panel drills into it.

page
drill

array of object

The sources feeding it, with their SQL.

Every data source feeding the panel, in order. Replaces the list.

dataSourceIdstringrequired
The data source, from List Analytics Data Sources.
aliasstring
The name the query and transform code use for the source's rows. Made from the source's name when left out.
querystring
DuckDB SQL over the source's rows, with the alias as the table name: filter, group, sort and limit here. An empty string shows every row.
followPageDateboolean
false keeps the page's date filter off this source (an all-time figure).

string

Code combining the sources, when SQL cannot.

JavaScript function body receiving each source as a named input ({ alias }) and returning the rows to show. Use it only for what SQL cannot do. Saving it runs it; read the result with Get Analytics Panel Output. An empty string removes it.

string

How it draws its rows.

How the panel draws its rows. One of: table, bar, line, combo, pareto, bump, scatter, bubble, quadrant, pie, treemap, heatmap, pivot, cohort, statusgrid, activity, funnel, waterfall, sankey, chord, statetimeline, timeline, stat, trend, progress, gauge, bullet, report, document, workbook, html, map, region, tabs, group.

table
bar
line
combo
pareto
bump
scatter
bubble
quadrant
pie
treemap
heatmap
pivot
cohort
statusgrid
activity
funnel
waterfall
sankey
chord
statetimeline
timeline
stat
trend
progress
gauge
bullet
report
document
workbook
html
map
region
tabs
group

array of object

Table columns, in order.

Table panels: the columns shown, in order. Replaces the list; an empty list lets the panel pick its columns from the rows.

keystringrequired
The row key to show (dot paths allowed). A button column takes an identifier you choose, which names its click event "button:<key>".
typestring
How the value is formatted: string, number, percent, ratio, currency, duration, rank, boolean, date, object, list, html, button.
- string
- number
- percent
- ratio
- currency
- duration
- rank
- boolean
- date
- object
- list
- html
- button
labelstring
Button columns: the text on the button.
tooltipstring
Button columns: one sentence shown on hover.
widthnumber or string
The width in pixels, 64-800. An empty string returns it to the width of its content.

object

Value formats by column.

How each column's values are formatted, keyed by column: { "<column>": { "type": "currency" } }. Merged over what is stored; null for a column takes its format off.

object

Cell links by column.

Table panels: the link each cell of a column opens, keyed by column. Merged over what is stored; null for a column takes its link off.

object

Colours by series or category.

The color of each series or category, keyed by its name. Merged over what is stored; null for a name takes its color off.

object

The display type's settings.

The settings of the panel's display type, keyed by block (annotations, tooltip, chart, bump, scatter, pie, treemap, cellGrid, statusGrid, activity, funnel, waterfall, sankey, chord, statetimeline, stat, trend, target, report, document, workbook, html, map, region, tabs, group), as Get Analytics Panel answers them. A block is refused on a type that does not draw it.

annotationsobject
The annotations settings. A block you send is merged over the stored one: send only the fields you change.
tooltipobject
The tooltip settings. A block you send is merged over the stored one: send only the fields you change.
chartobject
The chart settings. A block you send is merged over the stored one: send only the fields you change.
bumpobject
The bump settings. A block you send is merged over the stored one: send only the fields you change.
scatterobject
The scatter settings. A block you send is merged over the stored one: send only the fields you change.
pieobject
The pie settings. A block you send is merged over the stored one: send only the fields you change.
treemapobject
The treemap settings. A block you send is merged over the stored one: send only the fields you change.
cellGridobject
The cellGrid settings. A block you send is merged over the stored one: send only the fields you change.
statusGridobject
The statusGrid settings. A block you send is merged over the stored one: send only the fields you change.
activityobject
The activity settings. A block you send is merged over the stored one: send only the fields you change.
funnelobject
The funnel settings. A block you send is merged over the stored one: send only the fields you change.
waterfallobject
The waterfall settings. A block you send is merged over the stored one: send only the fields you change.
sankeyobject
The sankey settings. A block you send is merged over the stored one: send only the fields you change.
chordobject
The chord settings. A block you send is merged over the stored one: send only the fields you change.
statetimelineobject
The statetimeline settings. A block you send is merged over the stored one: send only the fields you change.
statobject
The stat settings. A block you send is merged over the stored one: send only the fields you change.
trendobject
The trend settings. A block you send is merged over the stored one: send only the fields you change.
targetobject
The target settings. A block you send is merged over the stored one: send only the fields you change.
reportobject
The report settings. A block you send is merged over the stored one: send only the fields you change.
documentobject
The document settings. A block you send is merged over the stored one: send only the fields you change.
workbookobject
The workbook settings. A block you send is merged over the stored one: send only the fields you change.
htmlobject
The html settings. A block you send is merged over the stored one: send only the fields you change.
mapobject
The map settings. A block you send is merged over the stored one: send only the fields you change.
regionobject
The region settings. A block you send is merged over the stored one: send only the fields you change.
tabsobject
The tabs settings. A block you send is merged over the stored one: send only the fields you change. { items: [panel ids], ... } replaces the child list; null releases every child back to the grid.
groupobject
The group settings. A block you send is merged over the stored one: send only the fields you change. { items: [panel ids], ... } replaces the child list; null releases every child back to the grid.

object

Click wiring by event.

What clicking the panel's items does, keyed by event: rowClick, valueClick and the other events the display type fires, or "button:<column key>" for a button column. Replaces every wiring; null clears them all.

object

Make a stat tile flip a toggle variable.

Stat panels: make the tile a control that flips a toggle page variable. null makes it a normal panel again.

togglesstringrequired
The toggle page variable the tile flips.

object

Labels for a drill-down panel's $params.

Drill-down panels: labels for the $params the source SQL reads, keyed by param. Replaces them; null clears them.

string

Code returning the display settings.

Advanced display: JavaScript function body that returns the display settings from the page variables. It is run when you save. An empty string goes back to the static settings and keeps the code.

string

A report's AI-written sections.

Report panels: JavaScript function body returning { KEY: { prompt, additionalContext } } for the {{KEY}} tokens the transform writes. An empty string removes it.

object

Its place on the grid.

The panel's place on the page's 12-column grid.

xnumberrequired
Leftmost column, 0-11.
ynumberrequired
Top row, from 0.
wnumberrequired
Width in columns, 1-12.
hnumber
Height in rows (about 48px each). Leave it out to keep the current height.

string

auto to take a fixed height off.

auto takes a fixed height off, so the panel is as tall as what it shows.

auto

Response fields

idstring

The panel id.

pageIdstring

The page the panel is on, from List Analytics Pages.

namestring

The panel's title, shown in its card header.

descriptionstring

The line under the title when the panel opens as a full-page drill-down view.

placementstring

Where the panel shows.

pageOn the page grid.
drillOff the grid: it opens when a click on another panel drills into it, narrowed by the clicked row.

displayTypestring

tableDraws a table panel.
barDraws a bar panel.
lineDraws a line panel.
comboDraws a combo panel.
paretoDraws a pareto panel.
bumpDraws a bump panel.
scatterDraws a scatter panel.
bubbleDraws a bubble panel.
quadrantDraws a quadrant panel.
pieDraws a pie panel.
treemapDraws a treemap panel.
heatmapDraws a heatmap panel.
pivotDraws a pivot panel.
cohortDraws a cohort panel.
statusgridDraws a statusgrid panel.
activityDraws a activity panel.
funnelDraws a funnel panel.
waterfallDraws a waterfall panel.
sankeyDraws a sankey panel.
chordDraws a chord panel.
statetimelineDraws a statetimeline panel.
timelineDraws a timeline panel.
statDraws a stat panel.
trendDraws a trend panel.
progressDraws a progress panel.
gaugeDraws a gauge panel.
bulletDraws a bullet panel.
reportDraws a report panel.
documentDraws a document panel.
workbookDraws a workbook panel.
htmlDraws a html panel.
mapDraws a map panel.
regionDraws a region panel.
tabsDraws a tabs panel.
groupDraws a group panel.

dataSourcesarray of objects

The data sources feeding the panel, in order.

dataSourceIdstring
The data source, from List Analytics Data Sources.
aliasstring
The name the source's query and the transform code use for its rows.
querystring
DuckDB SQL over this source's rows, with the alias as the table name. Empty when the panel shows every row as stored.
followPageDateboolean
Whether the page's date filter narrows this source. False for an all-time figure on a date-filtered page.

transformCodestring

JavaScript function body that receives each source as a named input and returns the rows to show. Empty when the source queries return the rows directly.

columnsarray of objects

Table panels: the columns shown, in order. Null when the panel picks its columns from the rows.

keystring
The row key the column shows (dot paths allowed). For a button column, the identifier that names its click event.
typestring
How the value is formatted and aligned. Absent for plain text.
- stringFormats the value as string.
- numberFormats the value as number.
- percentFormats the value as percent.
- ratioFormats the value as ratio.
- currencyFormats the value as currency.
- durationFormats the value as duration.
- rankFormats the value as rank.
- booleanFormats the value as boolean.
- dateFormats the value as date.
- objectFormats the value as object.
- listFormats the value as list.
- htmlFormats the value as html.
- buttonFormats the value as button.
labelstring
Button columns: the text on the button.
tooltipstring
Button columns: the sentence shown on hover.
widthnumber
The column width in pixels for everyone. Absent when the column is as wide as its content.

formatobject

How each column's values are formatted, keyed by column, for any display type: { "<column>": { "type": "currency", ... } }. Null when none is set.

linksobject

Table panels: the link each cell of a column opens, keyed by column. Null when none is set.

styleobject

The color of each series or category, keyed by its name. Null when none is set.

settingsobject

The settings of the panel's display type, keyed by block: annotations, tooltip, chart, bump, scatter, pie, treemap, cellGrid, statusGrid, activity, funnel, waterfall, sankey, chord, statetimeline, stat, trend, target, report, document, workbook, html, map, region, tabs, group. Only the blocks the panel stores are present.

onobject

What clicking the panel's items does, keyed by event (rowClick, valueClick, "button:<column key>" ...): { "rowClick": { "action": "navigatePage", "pageId": "..." } }. Empty when nothing is wired.

interactionobject

Stat panels: the toggle page variable a click on the tile flips. Null for a normal panel.

togglesstring
The toggle page variable.

paramsobject

Drill-down panels: the human label of each $param its SQL reads, keyed by param: { "userId": { "label": "User", "labeledBy": "userName" } }. Null when none is declared.

displayModestring

Whether the display comes from the settings or from displayCode.

basicThe display settings above.
advanceddisplayCode returns the display settings from the page variables.

displayCodestring

JavaScript function body that returns the display settings from the page variables. Kept, but unused, while displayMode is basic.

aiSnippetsCodestring

Report panels: JavaScript function body returning the AI-written sections of the report. Empty when it has none.

layoutobject

The panel's place on the page grid. Null when it was never placed (it then flows full width in creation order), and for a drill-down or a panel inside a container.

xnumber
Leftmost column on the 12-column grid, 0-11.
ynumber
Top row, from 0.
wnumber
Width in columns, 1-12.
hnumber
Height in rows (one row is about 48px). Null when the panel is as tall as what it shows.

tabIdstring

The page tab the panel sits on, from Get Analytics Page. Null on a page without tabs, and for a drill-down or a panel inside a container.

containedBystring

The container panel (tabs or group) it renders inside, or null when it sits on the grid or is a drill-down.

createdOndate

When the panel was created. Null on a published version of the page.

updatedOndate

When the panel last changed. Null on a published version of the page.