# Get Analytics Page Definition

Read a page's whole draft as one document, in the shape Set Analytics Page Definition takes: change it and send it back. The ETag header carries its revision.

`GET https://connect.mindcloud.co/v2/analytics/pages/:pageId/definition`

Permissions: `analytics:page:view`.

## Parameters

### Path

- `pageId` (string, required): The page id, from List Analytics Pages.

### Headers

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

## Example request

```bash
curl --request GET \
  --url 'https://connect.mindcloud.co/v2/analytics/pages/Pq7Lm2Xc9RtA/definition' \
  --header 'Authorization: Bearer $MINDCLOUD_API_TOKEN'
```

## Response fields

- `page` (object): The page settings, as Update Analytics Page takes them.
  - `name` (string): The page title.
  - `description` (string): The line under the title, or null.
  - `icon` (string): The page icon id, or null.
  - `iconColor` (string): The page icon color, or null.
  - `fullWidth` (boolean): Whether the page spans the whole window.
  - `showPanelSources` (boolean): Whether each panel shows its data sources' app icons.
  - `themeId` (string): The page theme, from List Analytics Themes, or null when it follows its folder or the company default.
  - `style` (object): Style overrides on top of the theme, by option key, or null.
  - `isPaused` (boolean): Whether the page's own data refreshes are paused.
- `variables` (array of objects): The page variables (its filters), in page order, as Set Analytics Page Variables takes them.
  - `name` (string): The variable name. Queries read it as $<name>.
  - `type` (string): What it holds.
    Allowed values:
      - `dateRange`: A date window.
      - `select`: One value, or several with multiple, from a list of choices.
      - `search`: Free text a viewer types.
      - `toggle`: An on or off switch.
  - `control` (string): chip shows a picker on the page; none has no picker.
    Allowed values:
      - `chip`
      - `none`
  - `label` (string): The picker label.
  - `default` (object): What the page opens with: a date preset or range, all or a choice value, or true or false for a toggle.
  - `multiple` (boolean): A select that takes several choices.
  - `labeledBy` (string): A select set by a row click: the clicked row field that names the value.
  - `options` (object): A select: where its choices come from, as dataSourceId with query or valueField and labelField, or typed values.
  - `presets` (array): A dateRange: its preset menu, in order.
  - `showCalendar` (boolean): A dateRange: false allows presets only.
  - `timeGranularity` (boolean): A dateRange: custom ranges carry times.
- `tabs` (array of objects): The page tabs, in order, or null when the page has none.
  - `id` (string): The tab id.
  - `name` (string): The tab name.
- `panels` (array of objects): Every panel in the draft, in the shape Update Analytics Panel takes, with its grid place and tab.
  - `id` (string): The panel id.
  - `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): 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): 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: { "<column>": { "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:<column key>" ...): { "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.
  - `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.
- `revision` (string): The draft revision: send it in If-Match to Set Analytics Page Definition. It changes whenever anything in this definition does.