CDPGuidesSupport

Insights

Create saved Insight reports, preview event metrics, and retrieve results with date, smoothing, cumulative, and comparison overrides.

Insights chart event counts, unique visitors, sums, and averages over time. Use this API to save reports, check which options are supported, preview an unsaved report, and fetch results. The Insights guide shows the same report in the app.

Reading requires web-analytics:view and writing requires web-analytics:write. Both also need variables:find-custom and Insights access for your organization.

Updates, deletes, and saved results take the report's current expectedRevision. A stale one returns 409, and a report you cannot open returns 404. Date, smoothing, cumulative, and comparison overrides on a result apply to that request only. Structured query parameters are JSON-encoded, and an explicit null is sent as null.

GET/rest/v1/insights

GET
/rest/v1/insights

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

limit?|

Maximum number of items to return. Defaults to 25; values below 1 are clamped to 1 and values above 100 are clamped to 100.

cursor?string

Opaque pagination cursor from pagination.nextCursor in the previous response. Do not decode or modify it. Malformed cursors return 400 Bad Request.

search?string

Case-insensitive search in the name and description.

Lengthlength <= 200

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/insights"
{  "entities": [    {      "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"    }  ],  "pagination": {    "nextCursor": "string",    "hasMore": true  },  "unavailableCount": 0,  "warnings": [    {      "code": "string",      "message": "string",      "path": [        "string"      ]    }  ]}

POST/rest/v1/insights

POST
/rest/v1/insights
*object
object
object
object

Authorization

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/insights" \  -H "Content-Type: application/json" \  -d '{    "name": "string",    "definition": {      "version": 1,      "kind": "insight",      "metrics": [        {          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",          "name": "string",          "eventNames": [            "string"          ],          "aggregation": "event_count"        }      ],      "interval": "day"    },    "reportContext": {      "dateRange": {        "from": "string",        "to": "string"      }    },    "view": {}  }'
{  "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"}

GET/rest/v1/insights/{id}

GET
/rest/v1/insights/{id}

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string
Formatuuid

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/insights/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "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"}

PATCH/rest/v1/insights/{id}

PATCH
/rest/v1/insights/{id}
*object
object
object
object

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string
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/insights/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",  "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"}

DELETE/rest/v1/insights/{id}

DELETE
/rest/v1/insights/{id}

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string
Formatuuid

Query Parameters

expectedRevision*string

Revision returned by get/list 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/insights/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"}

GET/rest/v1/insights/capabilities

GET
/rest/v1/insights/capabilities

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/insights/capabilities"
{  "definitionVersion": 1,  "supportedAggregations": [    "event_count"  ],  "supportedIntervals": [    "day"  ],  "supportedVisualizations": [    "line"  ],  "supportedSmoothing": [    "none"  ],  "maxMetrics": 10,  "maxEventNamesPerMetric": 10,  "maxDateRangeDays": 366,  "minSmoothingWindow": 2,  "maxSmoothingWindow": 30,  "supportsReportFilter": true,  "supportsMetricFilter": true,  "supportsNumericProperty": true,  "supportsNonUtcTimeZones": false,  "supportedDatePresets": [    "today"  ],  "supportedAxisScales": [    "linear"  ],  "supportedCumulativeAggregations": [    "event_count"  ],  "supportsBreakdowns": false,  "supportsComparisons": true,  "supportedComparisons": [    "previous_period"  ]}

GET/rest/v1/insights/preview

GET
/rest/v1/insights/preview

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Query Parameters

input*string

Object with required definition and reportContext, plus optional smoothingWindow, cumulative, and comparison. Chart view settings belong to saved reports. JSON-encode input in the REST query string; maximum 16384 bytes.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/rest/v1/insights/preview?input=string"
{  "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/insights/{id}/result

GET
/rest/v1/insights/{id}/result

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Path Parameters

id*string
Formatuuid

Query Parameters

expectedRevision*string

Revision returned by get/list or the last write. A stale revision returns 409; reload before retrying.

Formatuuid
reportContextOverride?string

Complete date range override for this query. JSON-encoded in the REST query string; does not change the saved report.

smoothingWindowOverride?|

Omit to use saved smoothing, send null to disable it, or supply a window of 2–30 buckets.

Range2 <= value <= 30
cumulativeOverride?|

Omit or send null to use the saved cumulative setting; true or false overrides it for this query.

comparison?string

Compare with the previous period, previous year, or a custom starting date. 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/insights/497f6eca-6276-4993-bfeb-53cbbbba6f08/result?expectedRevision=497f6eca-6276-4993-bfeb-53cbbbba6f08"
{  "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"}

Next Steps

How is this guide?

Dashboards

Previous Page

Funnels

Next Page