# 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 https://connect.mindcloud.co/v2/analytics/pages/:pageId/panels/:panelId` Permissions: `analytics:page:edit`. ## Parameters ### Path - `pageId` (string, required): The page id, from List Analytics Pages. - `panelId` (string, required): The panel id, from Get Analytics Page or Create Analytics Panel. ### Headers - `If-Match` (string, required): 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. - `X-Company-Id` (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](https://mindcloud.co/docs/api/rest/introduction/organizations). ### Body - `name` (string): The panel's title. The panel's title. Setting it turns off automatic renaming for this panel. - `description` (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. - `placement` (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. Allowed values: - `page` - `drill` - `dataSources` (array): The sources feeding it, with their SQL. Every data source feeding the panel, in order. Replaces the list. - `dataSourceId` (string, required): The data source, from List Analytics Data Sources. - `alias` (string): The name the query and transform code use for the source's rows. Made from the source's name when left out. - `query` (string): 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. - `followPageDate` (boolean): false keeps the page's date filter off this source (an all-time figure). - `transformCode` (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. - `displayType` (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. Allowed values: - `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` - `columns` (array): 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. - `key` (string, required): The row key to show (dot paths allowed). A button column takes an identifier you choose, which names its click event "button:". - `type` (string): How the value is formatted: string, number, percent, ratio, currency, duration, rank, boolean, date, object, list, html, button. Allowed values: - `string` - `number` - `percent` - `ratio` - `currency` - `duration` - `rank` - `boolean` - `date` - `object` - `list` - `html` - `button` - `label` (string): Button columns: the text on the button. - `tooltip` (string): Button columns: one sentence shown on hover. - `width` (number or string): The width in pixels, 64-800. An empty string returns it to the width of its content. - `format` (object): Value formats by column. How each column's values are formatted, keyed by column: { "": { "type": "currency" } }. Merged over what is stored; null for a column takes its format off. - `links` (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. - `style` (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. - `settings` (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. - `annotations` (object): The annotations settings. A block you send is merged over the stored one: send only the fields you change. - `tooltip` (object): The tooltip settings. A block you send is merged over the stored one: send only the fields you change. - `chart` (object): The chart settings. A block you send is merged over the stored one: send only the fields you change. - `bump` (object): The bump settings. A block you send is merged over the stored one: send only the fields you change. - `scatter` (object): The scatter settings. A block you send is merged over the stored one: send only the fields you change. - `pie` (object): The pie settings. A block you send is merged over the stored one: send only the fields you change. - `treemap` (object): The treemap settings. A block you send is merged over the stored one: send only the fields you change. - `cellGrid` (object): The cellGrid settings. A block you send is merged over the stored one: send only the fields you change. - `statusGrid` (object): The statusGrid settings. A block you send is merged over the stored one: send only the fields you change. - `activity` (object): The activity settings. A block you send is merged over the stored one: send only the fields you change. - `funnel` (object): The funnel settings. A block you send is merged over the stored one: send only the fields you change. - `waterfall` (object): The waterfall settings. A block you send is merged over the stored one: send only the fields you change. - `sankey` (object): The sankey settings. A block you send is merged over the stored one: send only the fields you change. - `chord` (object): The chord settings. A block you send is merged over the stored one: send only the fields you change. - `statetimeline` (object): The statetimeline settings. A block you send is merged over the stored one: send only the fields you change. - `stat` (object): The stat settings. A block you send is merged over the stored one: send only the fields you change. - `trend` (object): The trend settings. A block you send is merged over the stored one: send only the fields you change. - `target` (object): The target settings. A block you send is merged over the stored one: send only the fields you change. - `report` (object): The report settings. A block you send is merged over the stored one: send only the fields you change. - `document` (object): The document settings. A block you send is merged over the stored one: send only the fields you change. - `workbook` (object): The workbook settings. A block you send is merged over the stored one: send only the fields you change. - `html` (object): The html settings. A block you send is merged over the stored one: send only the fields you change. - `map` (object): The map settings. A block you send is merged over the stored one: send only the fields you change. - `region` (object): The region settings. A block you send is merged over the stored one: send only the fields you change. - `tabs` (object): 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. - `group` (object): 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. - `on` (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:" for a button column. Replaces every wiring; null clears them all. - `interaction` (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. - `toggles` (string, required): The toggle page variable the tile flips. - `params` (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. - `displayCode` (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. - `aiSnippetsCode` (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. - `layout` (object): Its place on the grid. The panel's place on the page's 12-column grid. - `x` (number, required): Leftmost column, 0-11. - `y` (number, required): Top row, from 0. - `w` (number, required): Width in columns, 1-12. - `h` (number): Height in rows (about 48px each). Leave it out to keep the current height. - `heightMode` (string): auto to take a fixed height off. auto takes a fixed height off, so the panel is as tall as what it shows. Allowed values: - `auto` ## Example request ```bash curl --request PUT \ --url 'https://connect.mindcloud.co/v2/analytics/pages/Pq7Lm2Xc9RtA/panels/Kd4Rw8Zn1VbQ' \ --header 'Authorization: Bearer $MINDCLOUD_API_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "name": "Orders by month", "dataSources": [ { "dataSourceId": "Ds3Hq9Lp2WxM", "query": "SELECT date_trunc('\''month'\'', created_on) AS month, count(*) AS orders FROM orders GROUP BY 1 ORDER BY 1" } ], "displayType": "bar", "settings": { "chart": { "xKey": "month", "series": [ { "key": "orders" } ] } } }' ``` ## Response fields - `id` (string): The panel id. - `pageId` (string): The page the panel is on, from List Analytics Pages. - `name` (string): The panel's title, shown in its card header. - `description` (string): The line under the title when the panel opens as a full-page drill-down view. - `placement` (string): Where the panel shows. Allowed values: - `page`: On the page grid. - `drill`: Off the grid: it opens when a click on another panel drills into it, narrowed by the clicked row. - `displayType` (string): 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. Allowed values: - `table`: Draws a table panel. - `bar`: Draws a bar panel. - `line`: Draws a line panel. - `combo`: Draws a combo panel. - `pareto`: Draws a pareto panel. - `bump`: Draws a bump panel. - `scatter`: Draws a scatter panel. - `bubble`: Draws a bubble panel. - `quadrant`: Draws a quadrant panel. - `pie`: Draws a pie panel. - `treemap`: Draws a treemap panel. - `heatmap`: Draws a heatmap panel. - `pivot`: Draws a pivot panel. - `cohort`: Draws a cohort panel. - `statusgrid`: Draws a statusgrid panel. - `activity`: Draws a activity panel. - `funnel`: Draws a funnel panel. - `waterfall`: Draws a waterfall panel. - `sankey`: Draws a sankey panel. - `chord`: Draws a chord panel. - `statetimeline`: Draws a statetimeline panel. - `timeline`: Draws a timeline panel. - `stat`: Draws a stat panel. - `trend`: Draws a trend panel. - `progress`: Draws a progress panel. - `gauge`: Draws a gauge panel. - `bullet`: Draws a bullet panel. - `report`: Draws a report panel. - `document`: Draws a document panel. - `workbook`: Draws a workbook panel. - `html`: Draws a html panel. - `map`: Draws a map panel. - `region`: Draws a region panel. - `tabs`: Draws a tabs panel. - `group`: Draws a group panel. - `dataSources` (array of objects): The data sources feeding the panel, in order. - `dataSourceId` (string): The data source, from List Analytics Data Sources. - `alias` (string): The name the source's query and the transform code use for its rows. - `query` (string): DuckDB SQL over this source's rows, with the alias as the table name. Empty when the panel shows every row as stored. - `followPageDate` (boolean): Whether the page's date filter narrows this source. False for an all-time figure on a date-filtered page. - `transformCode` (string): 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. - `columns` (array of objects): Table panels: the columns shown, in order. Null when the panel picks its columns from the rows. - `key` (string): The row key the column shows (dot paths allowed). For a button column, the identifier that names its click event. - `type` (string): How the value is formatted and aligned. Absent for plain text. Allowed values: - `string`: Formats the value as string. - `number`: Formats the value as number. - `percent`: Formats the value as percent. - `ratio`: Formats the value as ratio. - `currency`: Formats the value as currency. - `duration`: Formats the value as duration. - `rank`: Formats the value as rank. - `boolean`: Formats the value as boolean. - `date`: Formats the value as date. - `object`: Formats the value as object. - `list`: Formats the value as list. - `html`: Formats the value as html. - `button`: Formats the value as button. - `label` (string): Button columns: the text on the button. - `tooltip` (string): Button columns: the sentence shown on hover. - `width` (number): The column width in pixels for everyone. Absent when the column is as wide as its content. - `format` (object): How each column's values are formatted, keyed by column, for any display type: { "": { "type": "currency", ... } }. Null when none is set. - `links` (object): Table panels: the link each cell of a column opens, keyed by column. Null when none is set. - `style` (object): The color of each series or category, keyed by its name. Null when none is set. - `settings` (object): 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. - `on` (object): What clicking the panel's items does, keyed by event (rowClick, valueClick, "button:" ...): { "rowClick": { "action": "navigatePage", "pageId": "..." } }. Empty when nothing is wired. - `interaction` (object): Stat panels: the toggle page variable a click on the tile flips. Null for a normal panel. - `toggles` (string): The toggle page variable. - `params` (object): 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. - `displayMode` (string): Whether the display comes from the settings or from displayCode. Allowed values: - `basic`: The display settings above. - `advanced`: displayCode returns the display settings from the page variables. - `displayCode` (string): JavaScript function body that returns the display settings from the page variables. Kept, but unused, while displayMode is basic. - `aiSnippetsCode` (string): Report panels: JavaScript function body returning the AI-written sections of the report. Empty when it has none. - `layout` (object): 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. - `x` (number): Leftmost column on the 12-column grid, 0-11. - `y` (number): Top row, from 0. - `w` (number): Width in columns, 1-12. - `h` (number): Height in rows (one row is about 48px). Null when the panel is as tall as what it shows. - `tabId` (string): 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. - `containedBy` (string): The container panel (tabs or group) it renders inside, or null when it sits on the grid or is a drill-down. - `createdOn` (date): When the panel was created. Null on a published version of the page. - `updatedOn` (date): When the panel last changed. Null on a published version of the page.