CDPGuidesSupport

Dashboards

Combine saved Insights, Journeys, Funnels, text, and session replays in branded dashboards with shared dates, filters, layouts, and per-tile results.

Dashboards bring saved Insights, Journeys, and Funnels together under one set of dates and filters, alongside text and session replay tiles. Each tile keeps its report's own settings, and removing a tile or deleting a dashboard never deletes the reports. The Dashboards guide shows the same feature in the app.

Each tile holds exactly one of report, text, or replays, and every kind counts toward the 12-tile limit. Text tiles store markdown for headings and commentary. Replay tiles list the most recent matching recordings: their results combine the dashboard's dates and filter with the tile's own eventName, pathname, and filter, and return the effective date window with any retention warnings. Use replay-preview to try replay settings before saving them. The report branding logo appears on dashboards, their PDFs, and presentations. Read it (pass includeDataUrl=false for metadata only), replace it with a PNG, JPEG, or WebP image (convert SVG logos first), or remove it with the report branding operations below.

Updates and deletes take the dashboard's current expectedRevision, and a stale one returns 409 so you never overwrite a teammate's edit. A PATCH replaces any reportContext or tiles you send in full, and null clears a description or filter. Tile results use one absolute date range so every tile lines up. Include the dashboard's filter to apply it, or leave it out to use only each report's own filters. Comparison applies to Insight tiles. Structured query parameters are JSON-encoded.

GET/rest/v1/dashboards

GET
/rest/v1/dashboards
AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

limit?integer

Maximum dashboards to return. Defaults to 20; values above 100 are capped at 100. Each page scans at most 100 configurations in stable ID order, so pages may be short even when more results exist.

cursor?string

Opaque pagination.nextCursor from the previous page, scoped to the account and search text. Continue while pagination.hasMore is true; changing the search requires starting without a cursor.

search?string

Case-insensitive substring search on Dashboard names.

Lengthlength <= 200

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/dashboards"
{  "entities": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "revision": "b587a570-d9a5-40c2-87da-edba28b3005f",      "name": "string",      "description": "string",      "reportContext": {        "dateRange": {          "from": "string",          "to": "string",          "timeZone": "UTC"        }      },      "filter": {        "version": 1,        "filter": {          "kind": "and",          "children": [            {              "kind": "and",              "children": [                null              ]            }          ]        }      },      "tiles": [        {          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",          "report": {            "kind": "insight",            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"          },          "layout": {            "width": 3,            "height": 240          }        }      ],      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "createdByUserId": "string",      "updatedByUserId": "string"    }  ],  "pagination": {    "nextCursor": "string",    "hasMore": true  },  "unavailableCount": 0,  "warnings": [    {      "code": "string",      "message": "string"    }  ]}

POST/rest/v1/dashboards

POST
/rest/v1/dashboards
*object
object
array<object>
AuthorizationBearer <token>

Ours Privacy API key

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/rest/v1/dashboards" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "reportContext": {      "dateRange": {        "from": "string",        "to": "string"      }    },    "tiles": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "report": {          "kind": "insight",          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"        },        "layout": {          "width": 3,          "height": 240        }      }    ]  }'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "revision": "b587a570-d9a5-40c2-87da-edba28b3005f",  "name": "string",  "description": "string",  "reportContext": {    "dateRange": {      "from": "string",      "to": "string",      "timeZone": "UTC"    }  },  "filter": {    "version": 1,    "filter": {      "kind": "and",      "children": [        {          "kind": "and",          "children": [            null          ]        }      ]    }  },  "tiles": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "report": {        "kind": "insight",        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"      },      "layout": {        "width": 3,        "height": 240      }    }  ],  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "createdByUserId": "string",  "updatedByUserId": "string"}

GET/rest/v1/dashboards/{id}

GET
/rest/v1/dashboards/{id}
AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Saved Dashboard identifier returned by list_dashboards or create_dashboard.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/dashboards/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "revision": "b587a570-d9a5-40c2-87da-edba28b3005f",  "name": "string",  "description": "string",  "reportContext": {    "dateRange": {      "from": "string",      "to": "string",      "timeZone": "UTC"    }  },  "filter": {    "version": 1,    "filter": {      "kind": "and",      "children": [        {          "kind": "and",          "children": [            null          ]        }      ]    }  },  "tiles": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "report": {        "kind": "insight",        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"      },      "layout": {        "width": 3,        "height": 240      }    }  ],  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "createdByUserId": "string",  "updatedByUserId": "string"}

PATCH/rest/v1/dashboards/{id}

PATCH
/rest/v1/dashboards/{id}
*object
object
array<object>
AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Saved Dashboard identifier returned by list_dashboards or create_dashboard.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/rest/v1/dashboards/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{    "expectedRevision": "01b5419f-7ce1-4016-a16c-802ea2b68a5e"  }'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "revision": "b587a570-d9a5-40c2-87da-edba28b3005f",  "name": "string",  "description": "string",  "reportContext": {    "dateRange": {      "from": "string",      "to": "string",      "timeZone": "UTC"    }  },  "filter": {    "version": 1,    "filter": {      "kind": "and",      "children": [        {          "kind": "and",          "children": [            null          ]        }      ]    }  },  "tiles": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "report": {        "kind": "insight",        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"      },      "layout": {        "width": 3,        "height": 240      }    }  ],  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "createdByUserId": "string",  "updatedByUserId": "string"}

DELETE/rest/v1/dashboards/{id}

DELETE
/rest/v1/dashboards/{id}
AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Saved Dashboard identifier returned by list_dashboards or create_dashboard.

Formatuuid

Query Parameters

expectedRevision*string

Current revision from get_dashboard, list_dashboards, or the last write. A stale revision returns 409; reload before retrying.

Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/rest/v1/dashboards/497f6eca-6276-4993-bfeb-53cbbbba6f08?expectedRevision=497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "deleted": true,  "deletedRevision": "cb5c94d3-b0a8-48db-bf1e-b2828973ba39"}

POST/rest/v1/dashboards/{id}/duplicate

POST
/rest/v1/dashboards/{id}/duplicate
*object
AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Saved Dashboard identifier returned by list_dashboards or create_dashboard.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/rest/v1/dashboards/497f6eca-6276-4993-bfeb-53cbbbba6f08/duplicate" \  -H "Content-Type: application/json" \  -d '{    "expectedRevision": "01b5419f-7ce1-4016-a16c-802ea2b68a5e"  }'
{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "revision": "b587a570-d9a5-40c2-87da-edba28b3005f",  "name": "string",  "description": "string",  "reportContext": {    "dateRange": {      "from": "string",      "to": "string",      "timeZone": "UTC"    }  },  "filter": {    "version": 1,    "filter": {      "kind": "and",      "children": [        {          "kind": "and",          "children": [            null          ]        }      ]    }  },  "tiles": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "report": {        "kind": "insight",        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"      },      "layout": {        "width": 3,        "height": 240      }    }  ],  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "createdByUserId": "string",  "updatedByUserId": "string"}

GET/rest/v1/dashboards/preview

GET
/rest/v1/dashboards/preview
AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

input*string

Required preview input: tileId, report { kind, id }, and context { from, to, filter? }; comparison is optional. JSON-encode this object in the REST query string; maximum 16384 bytes before URL encoding. Preview does not save a Dashboard or change the report.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/dashboards/preview?input=%7B%22tileId%22%3A%2211111111-1111-4111-8111-111111111111%22%2C%22report%22%3A%7B%22kind%22%3A%22insight%22%2C%22id%22%3A%2222222222-2222-4222-8222-222222222222%22%7D%2C%22context%22%3A%7B%22from%22%3A%222026-09-01%22%2C%22to%22%3A%222026-09-07%22%7D%2C%22comparison%22%3A%7B%22kind%22%3A%22previous_period%22%7D%7D"
{  "kind": "insight",  "tileId": "9db048b2-8e44-4092-82af-95bc11c3d9a3",  "computedAt": "2019-08-24T14:15:22Z",  "report": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "revision": "b587a570-d9a5-40c2-87da-edba28b3005f",    "name": "string",    "description": "string",    "definition": {      "version": 1,      "kind": "insight",      "metrics": [        {          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",          "name": "string",          "eventNames": [            "string"          ],          "aggregation": "event_count",          "property": {            "property": "event.properties",            "type": "number",            "path": [              "string"            ]          },          "filter": {            "version": 1,            "filter": {              "kind": "and",              "children": [                {                  "kind": "and",                  "children": []                }              ]            }          }        }      ],      "filter": {        "version": 1,        "filter": {          "kind": "and",          "children": [            {              "kind": "and",              "children": []            }          ]        }      },      "interval": "day"    },    "reportContext": {      "dateRange": {        "from": "string",        "to": "string",        "timeZone": "UTC"      }    },    "view": {      "visualization": "line",      "stacked": true,      "yAxisScale": "linear",      "cumulative": true,      "series": [        {          "metricId": "c2cc9ad9-a69d-40a3-8e01-a95e09e71978",          "color": "string",          "hidden": true        }      ],      "tableSort": {        "column": "label",        "direction": "asc"      },      "smoothing": "none",      "smoothingWindow": 2    },    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "createdByUserId": "string",    "updatedByUserId": "string"  },  "result": {    "semanticVersion": 1,    "engine": "clickhouse",    "sourcePolicy": "string",    "sourceRevision": "string",    "sourceLimitations": [      "string"    ],    "scope": {      "from": "string",      "to": "string",      "interval": "day",      "timeZone": "UTC",      "sourceCompleteness": "unknown",      "executedAt": "2019-08-24T14:15:22Z",      "cumulative": true,      "comparison": {        "kind": "previous_period",        "from": "string",        "to": "string"      }    },    "series": [      {        "key": "string",        "metricId": "c2cc9ad9-a69d-40a3-8e01-a95e09e71978",        "label": "string",        "breakdownValues": [          {            "property": "string",            "value": "string"          }        ],        "comparison": "previous_period",        "aggregation": "event_count",        "points": [          {            "bucketStart": "2019-08-24T14:15:22Z",            "bucketEnd": "2019-08-24T14:15:22Z",            "isPartial": true,            "raw": 0,            "smoothed": 0,            "cumulative": 0          }        ],        "rangeValue": 0      }    ],    "reportId": "836df459-dc40-4aa1-972a-6eb0a864dff9",    "revision": "b587a570-d9a5-40c2-87da-edba28b3005f"  }}

GET/rest/v1/dashboards/{id}/tile-result

GET
/rest/v1/dashboards/{id}/tile-result
AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Saved Dashboard identifier returned by list_dashboards or create_dashboard.

Formatuuid

Query Parameters

expectedRevision*string

Current revision from get_dashboard, list_dashboards, or the last write. A stale revision returns 409; reload before retrying.

Formatuuid
tileId*string

Tile identifier from get_dashboard, or a new unique tile identifier for a report preview.

Formatuuid
context*string

Complete execution context: inclusive UTC from/to dates and an optional temporary filter. Pass the saved Dashboard filter from get_dashboard to include it; omitting filter applies only report-native filters. Resolve dates once for every tile. This does not change the saved Dashboard or report.

comparison?string

Temporary comparison for Insight tiles only. JSON-encoded in the REST query string; never saved.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/dashboards/497f6eca-6276-4993-bfeb-53cbbbba6f08/tile-result?expectedRevision=497f6eca-6276-4993-bfeb-53cbbbba6f08&tileId=497f6eca-6276-4993-bfeb-53cbbbba6f08&context=string"
{  "kind": "insight",  "tileId": "9db048b2-8e44-4092-82af-95bc11c3d9a3",  "computedAt": "2019-08-24T14:15:22Z",  "report": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "revision": "b587a570-d9a5-40c2-87da-edba28b3005f",    "name": "string",    "description": "string",    "definition": {      "version": 1,      "kind": "insight",      "metrics": [        {          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",          "name": "string",          "eventNames": [            "string"          ],          "aggregation": "event_count",          "property": {            "property": "event.properties",            "type": "number",            "path": [              "string"            ]          },          "filter": {            "version": 1,            "filter": {              "kind": "and",              "children": [                {                  "kind": "and",                  "children": []                }              ]            }          }        }      ],      "filter": {        "version": 1,        "filter": {          "kind": "and",          "children": [            {              "kind": "and",              "children": []            }          ]        }      },      "interval": "day"    },    "reportContext": {      "dateRange": {        "from": "string",        "to": "string",        "timeZone": "UTC"      }    },    "view": {      "visualization": "line",      "stacked": true,      "yAxisScale": "linear",      "cumulative": true,      "series": [        {          "metricId": "c2cc9ad9-a69d-40a3-8e01-a95e09e71978",          "color": "string",          "hidden": true        }      ],      "tableSort": {        "column": "label",        "direction": "asc"      },      "smoothing": "none",      "smoothingWindow": 2    },    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z",    "createdByUserId": "string",    "updatedByUserId": "string"  },  "result": {    "semanticVersion": 1,    "engine": "clickhouse",    "sourcePolicy": "string",    "sourceRevision": "string",    "sourceLimitations": [      "string"    ],    "scope": {      "from": "string",      "to": "string",      "interval": "day",      "timeZone": "UTC",      "sourceCompleteness": "unknown",      "executedAt": "2019-08-24T14:15:22Z",      "cumulative": true,      "comparison": {        "kind": "previous_period",        "from": "string",        "to": "string"      }    },    "series": [      {        "key": "string",        "metricId": "c2cc9ad9-a69d-40a3-8e01-a95e09e71978",        "label": "string",        "breakdownValues": [          {            "property": "string",            "value": "string"          }        ],        "comparison": "previous_period",        "aggregation": "event_count",        "points": [          {            "bucketStart": "2019-08-24T14:15:22Z",            "bucketEnd": "2019-08-24T14:15:22Z",            "isPartial": true,            "raw": 0,            "smoothed": 0,            "cumulative": 0          }        ],        "rangeValue": 0      }    ],    "reportId": "836df459-dc40-4aa1-972a-6eb0a864dff9",    "revision": "b587a570-d9a5-40c2-87da-edba28b3005f"  }}

GET/rest/v1/dashboards/replay-preview

GET
/rest/v1/dashboards/replay-preview
AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

input*string

Required preview input: tileId, replays { limit, title?, eventName?, pathname?, filter? }, and context { from, to, filter? }. JSON-encode this object in the REST query string; maximum 16384 bytes before URL encoding. Preview does not save a Dashboard.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/dashboards/replay-preview?input=%7B%22tileId%22%3A%2211111111-1111-4111-8111-111111111111%22%2C%22replays%22%3A%7B%22title%22%3A%22Recent+checkouts%22%2C%22pathname%22%3A%22%2Fcheckout%22%2C%22limit%22%3A10%7D%2C%22context%22%3A%7B%22from%22%3A%222026-09-01%22%2C%22to%22%3A%222026-09-07%22%7D%7D"
{  "kind": "replays",  "tileId": "9db048b2-8e44-4092-82af-95bc11c3d9a3",  "computedAt": "2019-08-24T14:15:22Z",  "from": "string",  "to": "string",  "items": [    {      "sessionId": "string",      "visitorId": "string",      "date": "string",      "duration": 0,      "eventCount": 0,      "pageCount": 0,      "startTime": "string"    }  ],  "hasMore": true,  "warnings": [    {      "code": "string",      "message": "string"    }  ]}

GET/rest/v1/dashboards/{id}/replay-tile-result

GET
/rest/v1/dashboards/{id}/replay-tile-result
AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string

Saved Dashboard identifier returned by list_dashboards or create_dashboard.

Formatuuid

Query Parameters

expectedRevision*string

Current revision from get_dashboard, list_dashboards, or the last write. A stale revision returns 409; reload before retrying.

Formatuuid
tileId*string

Tile identifier from get_dashboard, or a new unique tile identifier for a report preview.

Formatuuid
context*string

Complete execution context: inclusive UTC from/to dates and an optional temporary filter, ANDed with the tile filter. Pass the saved Dashboard filter from get_dashboard to include it. Dates older than the organization replay retention are excluded and the window is limited to the most recent 61 days; the response reports the effective window and warnings.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/dashboards/497f6eca-6276-4993-bfeb-53cbbbba6f08/replay-tile-result?expectedRevision=497f6eca-6276-4993-bfeb-53cbbbba6f08&tileId=497f6eca-6276-4993-bfeb-53cbbbba6f08&context=string"
{  "kind": "replays",  "tileId": "9db048b2-8e44-4092-82af-95bc11c3d9a3",  "computedAt": "2019-08-24T14:15:22Z",  "from": "string",  "to": "string",  "items": [    {      "sessionId": "string",      "visitorId": "string",      "date": "string",      "duration": 0,      "eventCount": 0,      "pageCount": 0,      "startTime": "string"    }  ],  "hasMore": true,  "warnings": [    {      "code": "string",      "message": "string"    }  ]}
GET
/rest/v1/report-branding/logo
AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

includeDataUrl?boolean

Whether to return the image as logo.dataUrl. Defaults to true; pass false to read only the logo metadata.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/report-branding/logo"
{  "logo": {    "dataUrl": "string",    "contentType": "image/png",    "width": 0,    "height": 0,    "byteSize": 0,    "updatedAt": "2019-08-24T14:15:22Z",    "updatedByUserId": "string"  }}
PUT
/rest/v1/report-branding/logo
*object
AuthorizationBearer <token>

Ours Privacy API key

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/rest/v1/report-branding/logo" \  -H "Content-Type: application/json" \  -d '{    "contentType": "image/png",    "data": "string"  }'
{  "logo": {    "dataUrl": "string",    "contentType": "image/png",    "width": 0,    "height": 0,    "byteSize": 0,    "updatedAt": "2019-08-24T14:15:22Z",    "updatedByUserId": "string"  }}
DELETE
/rest/v1/report-branding/logo
AuthorizationBearer <token>

Ours Privacy API key

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X DELETE "https://example.com/rest/v1/report-branding/logo"
{  "logo": {    "dataUrl": "string",    "contentType": "image/png",    "width": 0,    "height": 0,    "byteSize": 0,    "updatedAt": "2019-08-24T14:15:22Z",    "updatedByUserId": "string"  }}

Next Steps

How is this guide?