---
title: "Analytics Dashboards API Reference | Linkbreakers"
description: "Saved analytics dashboards, for the whole workspace or one link: each widget names its data source and how it is charted."
canonical: "https://linkbreakers.com/help/api/analytics-dashboards"
---

# Analytics Dashboards

Saved analytics dashboards, for the whole workspace or one link: each widget names its data source and how it is charted.

7 entries on this page

## The analytics dashboard object

A workspace's analytics dashboard

`chatMessages` array of object

User-visible chat messages for rendering in the chat panel

4 child attributes

`id` string

`sender` string

"user" or "assistant"

`text` string

`timestamp` string (date-time)

`config` object

The structured configuration for a dashboard

2 child attributes

`gridColumns` integer (int32)

Width of the grid the widget positions and sizes are expressed in. Absent or 0 means the legacy two-column grid, where w=1 is half-width and w=2 is full-width. 8 is the former 8-column grid, still read. New dashboards use 24, which also divides into thirds.

`widgets` array of object

6 child attributes

`dataSource` object

What data to fetch

6 child attributes

`endpoint` string

The API endpoint path, e.g. "/v1/timeseries/events"

`method` string

HTTP method: "GET" or "POST"

`params` object

Static parameters always sent with the request

`responseDataPath` string

Dot-notation path to the data array in the response, e.g. "timeSeries.data" or "data" Empty string means the root object is the data (for single-value endpoints like metrics)

`usesDateRange` boolean

Whether the dashboard date range should be injected (startDate/endDate)

`usesInterval` boolean

Whether interval calculation should be injected (for time-bucketed data)

`id` string

Unique widget identifier

`position` object

Grid position

2 child attributes

`x` integer (int32)

Leftmost column the widget occupies, 0-based

`y` integer (int32)

Topmost row the widget occupies, 0-based

`size` object

Grid size

2 child attributes

`h` integer (int32)

Row span, one row being roughly 80px tall

`w` integer (int32)

Column span. In a 24-column config: 24 = full width, 12 = half, 8 = third, 6 = quarter.

`title` string

Display title

`visualization` object

How to visualize the data

4 child attributes

`chartType` string

Chart type: "bar", "horizontal\_bar", "line", "area", "stacked\_area", "pie", "number", "number\_trend", "list", "funnel", "location\_map"

`colors` array of string

Ordered list of colors for chart series/segments

`fieldMappings` array of object

Maps response fields to chart roles

`tabs` array of object

Optional tabs for grouped views. Each tab has label and params that override the base params.

`createdAt` string (date-time)

`id` string

`linkId` string

Link this dashboard is scoped to. Empty for the workspace-wide dashboard.

`name` string

`updatedAt` string (date-time)

Example analytics dashboard

```json
{
  "chatMessages": [
    {
      "id": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
      "sender": "string",
      "text": "string",
      "timestamp": "2026-01-15T09:30:00Z"
    }
  ],
  "config": {
    "gridColumns": 0,
    "widgets": [
      {
        "dataSource": {
          "endpoint": "string",
          "method": "string",
          "params": {},
          "responseDataPath": "string",
          "usesDateRange": false,
          "usesInterval": false
        },
        "id": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
        "position": {
          "x": 0,
          "y": 0
        },
        "size": {
          "h": 0,
          "w": 0
        },
        "title": "string",
        "visualization": {
          "chartType": "string",
          "colors": [
            "string"
          ],
          "fieldMappings": [
            {}
          ],
          "tabs": [
            {
              "mode": "WIDGET_TAB_MODE_DATA",
              "view": "WIDGET_TAB_VIEW_CHART"
            }
          ]
        }
      }
    ]
  },
  "createdAt": "2026-01-15T09:30:00Z",
  "id": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
  "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
  "name": "string",
  "updatedAt": "2026-01-15T09:30:00Z"
}
```

### Parameters

`linkId` string 

query

Restricts the result to the dashboard scoped to this link. Takes precedence over scope when both are set.

`scope` string 

query

Restricts the result by scope. Unset returns every dashboard.

* DASHBOARD\_SCOPE\_UNSPECIFIED: Every dashboard in the workspace, link-scoped or not.
* DASHBOARD\_SCOPE\_WORKSPACE: Only the workspace-wide dashboard, the one with no link.
* DASHBOARD\_SCOPE\_LINK: Only dashboards tied to a link.

`pageSize` integer (int64) 

query

Maximum number to return. Defaults to 100, capped at 1000.

`pageToken` string 

query

Cursor from a previous response's nextPageToken. Empty starts at the first page. Pages are ordered by (createdAt, id), which never change, so a record cannot move between pages while a client is walking them.

`cursor` string 

query

Opaque cursor from the previous page's nextPageToken. Same as pageToken; when both are sent, pageToken wins.

### Response

200

`dashboards` array of object

Fields: [The analytics dashboard object](#analytics-dashboards-object).

`nextPageToken` string

Cursor to continue listing dashboards. Empty on the last page.

`totalCount` integer (int64)

How many records exist in total, so a client can tell a complete answer from a page of one. A local-first client reads absence from this list as deletion, and may only do so when the count it was given matches what it received: without that, one page would look like the whole model and everything beyond it would be removed locally.

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X GET "https://api.linkbreakers.com/v1/analytics/dashboards" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

Response 200

```json
{
  "dashboards": [
    {
      "chatMessages": [
        {
          "id": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
          "sender": "string",
          "text": "string",
          "timestamp": "2026-01-15T09:30:00Z"
        }
      ],
      "config": {
        "gridColumns": 0,
        "widgets": [
          {
            "dataSource": {},
            "id": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
            "position": {},
            "size": {},
            "title": "string",
            "visualization": {}
          }
        ]
      },
      "createdAt": "2026-01-15T09:30:00Z",
      "id": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
      "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
      "name": "string",
      "updatedAt": "2026-01-15T09:30:00Z"
    }
  ],
  "nextPageToken": "string",
  "totalCount": 0
}
```

### Parameters

`dashboardId` string 

path

Required

`widgetId` string 

path

Required

### Response

200

`result` object

Absent when nothing has been generated yet

6 child attributes

`currentCount` integer (int32)

How many values exist now, for "N new answers since this ran"

`generatedAt` string (date-time)

When it was produced

`sourceCount` integer (int32)

How many values it was generated from

`stale` boolean

True when the underlying values have changed since it was generated, so a client can offer a re-run rather than presenting stale prose as current.

`text` string

The generated analysis

`widgetId` string

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X GET "https://api.linkbreakers.com/v1/analytics/dashboards/{dashboardId}/widgets/{widgetId}/summary" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

Response 200

```json
{
  "result": {
    "currentCount": 0,
    "generatedAt": "2026-01-15T09:30:00Z",
    "sourceCount": 0,
    "stale": false,
    "text": "string",
    "widgetId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f"
  }
}
```

### Parameters

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`config` object

Initial widgets. Empty means the dashboard starts with none, because its contents are normally agreed with the assistant before anything is created.

2 child attributes, the same as [config in the analytics dashboard object](#analytics-dashboards-object-config).

`id` string

Client-supplied dashboard id. Generated server-side when empty.

`linkId` string

Link to scope this dashboard to. Empty creates the workspace-wide dashboard.

`name` string

Display name. Defaults to "Default Dashboard" when empty.

`useDefaultWidgets` boolean

Fill the dashboard with a starter set instead of leaving it empty, for a dashboard made in one step rather than agreed in a conversation. Both sets open on three big numbers with their trend: visits, new visitors and returning visitors. Without linkId it is the workspace set (scans over time, top links, geography, technology and more). With linkId it is the link set: scans over time, geography, technology, peak hours, and new versus returning visitors, which is everything any link records. The service applies it to any link; whether it suits one is the caller's judgement, since a workflow that collects answers deserves widgets for them. Ignored when config is set, and hidden from the assistant, which agrees its widgets with the user and would otherwise stack them on top of these.

### Response

200

`dashboard` object

A workspace's analytics dashboard

Fields: [The analytics dashboard object](#analytics-dashboards-object).

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X POST "https://api.linkbreakers.com/v1/analytics/dashboards" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "config": {
    "gridColumns": 0,
    "widgets": [
      {
        "dataSource": {
          "endpoint": "string",
          "method": "string",
          "params": {},
          "responseDataPath": "string",
          "usesDateRange": false,
          "usesInterval": false
        },
        "id": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
        "position": {
          "x": 0,
          "y": 0
        },
        "size": {
          "h": 0,
          "w": 0
        },
        "title": "string",
        "visualization": {
          "chartType": "string",
          "colors": [
            "string"
          ],
          "fieldMappings": [
            {}
          ],
          "tabs": [
            {
              "mode": "WIDGET_TAB_MODE_DATA",
              "view": "WIDGET_TAB_VIEW_CHART"
            }
          ]
        }
      }
    ]
  },
  "id": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
  "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
  "name": "string",
  "useDefaultWidgets": false
}'
```

Response 200

```json
{
  "dashboard": {
    "chatMessages": [
      {
        "id": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
        "sender": "string",
        "text": "string",
        "timestamp": "2026-01-15T09:30:00Z"
      }
    ],
    "config": {
      "gridColumns": 0,
      "widgets": [
        {
          "dataSource": {
            "endpoint": "string",
            "method": "string",
            "params": {},
            "responseDataPath": "string",
            "usesDateRange": false,
            "usesInterval": false
          },
          "id": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
          "position": {
            "x": 0,
            "y": 0
          },
          "size": {
            "h": 0,
            "w": 0
          },
          "title": "string",
          "visualization": {
            "chartType": "string",
            "colors": [],
            "fieldMappings": [],
            "tabs": []
          }
        }
      ]
    },
    "createdAt": "2026-01-15T09:30:00Z",
    "id": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
    "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
    "name": "string",
    "updatedAt": "2026-01-15T09:30:00Z"
  }
}
```

### Parameters

`dashboardId` string 

path

Required

Dashboard holding the widget

`widgetId` string 

path

Required

Widget whose values should be analysed

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`force` boolean

Regenerate even when the stored result is still current

### Response

200

`result` object

A generated result for an on-demand widget tab.

6 child attributes

`currentCount` integer (int32)

How many values exist now, for "N new answers since this ran"

`generatedAt` string (date-time)

When it was produced

`sourceCount` integer (int32)

How many values it was generated from

`stale` boolean

True when the underlying values have changed since it was generated, so a client can offer a re-run rather than presenting stale prose as current.

`text` string

The generated analysis

`widgetId` string

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X POST "https://api.linkbreakers.com/v1/analytics/dashboards/{dashboardId}/widgets/{widgetId}/summary" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "force": false
}'
```

Response 200

```json
{
  "result": {
    "currentCount": 0,
    "generatedAt": "2026-01-15T09:30:00Z",
    "sourceCount": 0,
    "stale": false,
    "text": "string",
    "widgetId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f"
  }
}
```

### Parameters

`id` string 

path

Required

ID of the dashboard to update.

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`config` object

The structured configuration for a dashboard

2 child attributes, the same as [config in the analytics dashboard object](#analytics-dashboards-object-config).

`name` string

### Response

200

`dashboard` object

A workspace's analytics dashboard

Fields: [The analytics dashboard object](#analytics-dashboards-object).

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X PUT "https://api.linkbreakers.com/v1/analytics/dashboards/{id}" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "config": {
    "gridColumns": 0,
    "widgets": [
      {
        "dataSource": {
          "endpoint": "string",
          "method": "string",
          "params": {},
          "responseDataPath": "string",
          "usesDateRange": false,
          "usesInterval": false
        },
        "id": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
        "position": {
          "x": 0,
          "y": 0
        },
        "size": {
          "h": 0,
          "w": 0
        },
        "title": "string",
        "visualization": {
          "chartType": "string",
          "colors": [
            "string"
          ],
          "fieldMappings": [
            {}
          ],
          "tabs": [
            {
              "mode": "WIDGET_TAB_MODE_DATA",
              "view": "WIDGET_TAB_VIEW_CHART"
            }
          ]
        }
      }
    ]
  },
  "name": "string"
}'
```

Response 200

```json
{
  "dashboard": {
    "chatMessages": [
      {
        "id": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
        "sender": "string",
        "text": "string",
        "timestamp": "2026-01-15T09:30:00Z"
      }
    ],
    "config": {
      "gridColumns": 0,
      "widgets": [
        {
          "dataSource": {
            "endpoint": "string",
            "method": "string",
            "params": {},
            "responseDataPath": "string",
            "usesDateRange": false,
            "usesInterval": false
          },
          "id": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
          "position": {
            "x": 0,
            "y": 0
          },
          "size": {
            "h": 0,
            "w": 0
          },
          "title": "string",
          "visualization": {
            "chartType": "string",
            "colors": [],
            "fieldMappings": [],
            "tabs": []
          }
        }
      ]
    },
    "createdAt": "2026-01-15T09:30:00Z",
    "id": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
    "linkId": "3f6c2a5e-8b1d-4c7e-9a2f-5d8e1b0c4a7f",
    "name": "string",
    "updatedAt": "2026-01-15T09:30:00Z"
  }
}
```

### Parameters

`id` string 

path

Required

### Response

200

An empty JSON object.

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X DELETE "https://api.linkbreakers.com/v1/analytics/dashboards/{id}" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

---

Source: https://linkbreakers.com/help/api/analytics-dashboards
