Dashboards API - Ours Privacy

Combine saved Insights, Journeys, and Funnels in dashboards with shared dates, filters, layouts, and per-report results.

Dashboards bring up to 12 saved Insights, Journeys, and Funnels together under one set of dates and filters. 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.

Reading requires web-analytics:view and changing requires web-analytics:write. Tiles also respect the permissions of the report they show: Insights need variables:find-custom, and Journeys limited to specific sources need source:view. Your organization needs Analytics access.

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 UTC 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

Authorization

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`

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": []            }          ]        }      },      "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

Authorization

AuthorizationBearer <token>

Ours Privacy API key

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Display name for the saved Dashboard.

Length1 <= length <= 200

description?|

Optional description; null clears it.

Lengthlength <= 2000

reportContext*

Complete UTC date context. Replaces the saved context on PATCH. Funnel and Journey tiles support up to 91 inclusive days; Insights retain their native range limit.

filter?never

tiles*array<>

Ordered collection of up to 12 saved report references and layouts. Replaces the collection on PATCH; removing a tile does not delete its report. Referenced reports require web-analytics:view; Insights also require variables:find-custom and Journeys with selected sources require source:view.

Itemsitems <= 12

Response Body

`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": []        }      ]    }  },  "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}

Authorization

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`

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": []        }      ]    }  },  "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}

Authorization

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.

expectedRevision*string

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

Formatuuid

name?string

Display name for the saved Dashboard.

Length1 <= length <= 200

description?|

Optional description; null clears it.

Lengthlength <= 2000

reportContext?

Complete UTC date context. Replaces the saved context on PATCH. Funnel and Journey tiles support up to 91 inclusive days; Insights retain their native range limit.

filter?never

tiles?array<>

Itemsitems <= 12

Response Body

`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": []        }      ]    }  },  "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}

Authorization

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`

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

Authorization

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.

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`

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": []        }      ]    }  },  "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

Authorization

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`

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

Authorization

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`

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"  }}

Dashboards

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

500application/json

200application/json

400application/json

401application/json

403application/json

404application/json

409application/json

500application/json

Next Steps

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`