Skip to main content

Pivot dashboards API

You can use the Pivot dashboards API to create, read, and modify dashboards.

Pivot must be running in native users mode.

Get all dashboards

Returns a list of all dashboards.

URL

GET /api/v1/dashboards

Success response

CodeDescription
200"status": "ok"

Sample request

curl -X GET 'http://PIVOT_URL/api/v1/dashboards' \
--header 'x-imply-api-token:<token>'

Sample response

Show sample response
{
"dashboards": [
{
"name": "63b1",
"title": "Wikipedia: Top 7 european countries",
"type": "dashboard2",
"readAccess": {
"access": "all"
},
"modifyAccess": {
"access": "single",
"users": [
"admin@example.com"
]
},
"pages": [
{
"name": "page",
"label": "New page",
"tiles": [
{
"name": "t8075",
"type": "visualization",
"title": "Europe top 5",
"canExpand": true,
"description": "Number of events for the top 5 European countries",
"position": {
"width": 5,
"height": 5,
"y": 3
},
"facetEssence": {
"dataCube": "wikipedia00e7",
"timezone": "Etc/UTC",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"dynamic": {
"op": "timeRange",
"operand": {
"op": "ref",
"name": "m"
},
"duration": "P1D",
"step": -1
}
},
{
"dimension": "countryName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"United Kingdom",
"Germany",
"Spain",
"Italy",
"France"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"axesSplits": [
[
{
"dimension": "countryName",
"sortType": "measure",
"direction": "descending"
}
]
],
"visualization": "pie-chart",
"selectedMeasures": [
{
"measure": "count"
}
],
"pinnedDimensions": []
}
},
{
"name": "te111",
"type": "markdown",
"title": "Introduction",
"titleHidden": true,
"canExpand": true,
"description": "Introductory markdown tile",
"position": {
"width": 5,
"height": 3
},
"content": "## Wikipedia: General\n\nGeneral [Wikipedia](https://en.wikipedia.org/) dashboard showing:\n\n- Events for top 5 European cities\n"
}
]
}
]
},
{
"name": "33b7",
"title": "Wikipedia: France",
"type": "classic",
"readAccess": {
"access": "all"
},
"modifyAccess": {
"access": "single",
"users": [
"analyst@example.com"
]
},
"pages": [
{
"name": "page",
"label": "New page",
"tiles": [
{
"name": "t9193",
"type": "visualization",
"title": "Top 5 channels: France",
"canExpand": true,
"description": "Number of events for the top channels in France",
"position": {
"width": 6,
"height": 6,
"y": 3
},
"essence": {
"dataCube": "wikipedia00e7",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"dynamic": {
"op": "timeRange",
"operand": {
"op": "ref",
"name": "m"
},
"duration": "P1D",
"step": -1
}
},
{
"dimension": "countryName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"France"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"splits": [
{
"dimension": "channel",
"sortType": "measure",
"direction": "descending",
"limit": 5
}
],
"selectedMeasures": [
"count"
],
"pinnedDimensions": [],
"timezone": "Etc/UTC",
"visualization": "bar-chart",
"auxiliaryMeasures": []
}
},
{
"name": "t3541",
"type": "visualization",
"title": "Added by hour: France",
"canExpand": true,
"description": "Number of events added by hour for France",
"position": {
"width": 8,
"height": 6,
"x": 6,
"y": 3
},
"essence": {
"dataCube": "wikipedia00e7",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"dynamic": {
"op": "timeRange",
"operand": {
"op": "ref",
"name": "m"
},
"duration": "P1D",
"step": -1
}
},
{
"dimension": "countryName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"France"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"splits": [
{
"dimension": "__time",
"bucketAction": {
"op": "timeBucket",
"duration": "PT1H"
},
"sortType": "dimension",
"direction": "ascending"
}
],
"selectedMeasures": [
"count"
],
"pinnedDimensions": [],
"timezone": "Etc/UTC",
"visualization": "line-chart",
"auxiliaryMeasures": []
}
},
{
"name": "tc82f",
"type": "visualization",
"title": "Top 5 cities: France",
"canExpand": true,
"description": "Number of events for the top 5 cities in France",
"position": {
"width": 6,
"height": 3,
"x": 8
},
"essence": {
"dataCube": "wikipedia00e7",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"dynamic": {
"op": "timeRange",
"operand": {
"op": "ref",
"name": "m"
},
"duration": "P1D",
"step": -1
}
},
{
"dimension": "countryName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"France"
]
},
"exclude": false,
"mvFilterOnly": false
},
{
"dimension": "cityName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"Paris",
"Soissons",
"Champigny-sur-Marne",
"Chieulles",
"Dijon"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"splits": [
{
"dimension": "cityName",
"sortType": "measure",
"direction": "descending"
}
],
"selectedMeasures": [
"count"
],
"pinnedDimensions": [],
"timezone": "Etc/UTC",
"visualization": "table",
"auxiliaryMeasures": []
}
},
{
"name": "t350b",
"type": "visualization",
"title": "Events: France",
"canExpand": true,
"description": "Total number of events for countryname France",
"position": {
"width": 3,
"height": 3,
"x": 5
},
"essence": {
"dataCube": "wikipedia00e7",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"dynamic": {
"op": "timeRange",
"operand": {
"op": "ref",
"name": "m"
},
"duration": "P1D",
"step": -1
}
},
{
"dimension": "countryName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"France"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"splits": [],
"selectedMeasures": [
"count"
],
"pinnedDimensions": [],
"timezone": "Etc/UTC",
"visualization": "totals",
"auxiliaryMeasures": []
}
},
{
"name": "t2b8d",
"type": "markdown",
"title": "Introduction",
"titleHidden": true,
"canExpand": true,
"description": "Tile with introductory markdown",
"position": {
"width": 5,
"height": 3
},
"content": "## Wikipedia dashboard: France\n\nData for France from [Wikipedia](https://en.wikipedia.org/) sample dataset:\n- Top 5 channels\n- Top 5 cities\n- Events added by hour"
}
]
}
],
"filterTile": "hide"
},
{
"name": "Wikipedia_France",
"title": "Wikipedia: Total events for France",
"type": "classic",
"readAccess": {
"access": "all"
},
"modifyAccess": {
"access": "single",
"users": [
"analyst@example.com"
]
},
"pages": [
{
"name": "page",
"label": "New page",
"tiles": [
{
"name": "tf969",
"type": "visualization",
"title": "New tile",
"canExpand": true,
"description": "",
"position": {
"width": 4,
"height": 4
},
"essence": {
"dataCube": "wikipedia00e7",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"dynamic": {
"op": "timeRange",
"operand": {
"op": "ref",
"name": "m"
},
"duration": "P1D",
"step": -1
}
},
{
"dimension": "countryName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"France"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"splits": [],
"selectedMeasures": [
"count"
],
"pinnedDimensions": [],
"timezone": "Etc/UTC",
"visualization": "totals",
"auxiliaryMeasures": []
}
}
]
}
]
},
{
"name": "cd3a",
"title": "Wikipedia: Total events France",
"type": "classic",
"readAccess": {
"access": "all"
},
"modifyAccess": {
"access": "single",
"users": [
"analyst@example.com"
]
},
"pages": [
{
"name": "page",
"label": "New page",
"tiles": [
{
"name": "tf969",
"type": "visualization",
"title": "Total events - France",
"canExpand": true,
"description": "",
"position": {
"width": 4,
"height": 4
},
"essence": {
"dataCube": "wikipedia00e7",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"dynamic": {
"op": "timeRange",
"operand": {
"op": "ref",
"name": "m"
},
"duration": "P1D",
"step": -1
}
},
{
"dimension": "countryName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"France"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"splits": [],
"selectedMeasures": [
"count"
],
"pinnedDimensions": [],
"timezone": "Etc/UTC",
"visualization": "totals",
"auxiliaryMeasures": []
}
}
]
}
]
}
]
}

Get a dashboard

Returns a dashboard with a specified name. Note that the dashboard name is not the same as the name that appears in the Pivot UI. Get all dashboards to find the dashboard name.

URL

GET /api/v1/dashboards/{name}

Success response

CodeDescription
200"status": "ok"

Sample request

curl -X GET 'http://PIVOT_URL/api/v1/dashboards/63b1' \
--header 'x-imply-api-token:<token>'

Sample response

Show sample response
{
"dashboard": {
"name": "63b1",
"title": "Wikipedia: Top 7 european countries",
"type": "dashboard2",
"readAccess": {
"access": "all"
},
"modifyAccess": {
"access": "single",
"users": [
"analyst@example.com"
]
},
"pages": [
{
"name": "page",
"label": "New page",
"tiles": [
{
"name": "t8075",
"type": "visualization",
"title": "Europe top 5",
"canExpand": true,
"description": "Number of events for the top 5 European countries",
"position": {
"width": 5,
"height": 5,
"y": 3
},
"facetEssence": {
"dataCube": "wikipedia00e7",
"timezone": "Etc/UTC",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"dynamic": {
"op": "timeRange",
"operand": {
"op": "ref",
"name": "m"
},
"duration": "P1D",
"step": -1
}
},
{
"dimension": "countryName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"United Kingdom",
"Germany",
"Spain",
"Italy",
"France"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"axesSplits": [
[
{
"dimension": "countryName",
"sortType": "measure",
"direction": "descending"
}
]
],
"visualization": "pie-chart",
"selectedMeasures": [
{
"measure": "count"
}
],
"pinnedDimensions": []
}
},
{
"name": "te111",
"type": "markdown",
"title": "Introduction",
"titleHidden": true,
"canExpand": true,
"description": "Introductory markdown tile",
"position": {
"width": 5,
"height": 3
},
"content": "## Wikipedia: General\n\nGeneral [Wikipedia](https://en.wikipedia.org/) dashboard showing:\n\n- Events for top 5 European cities\n"
}
]
}
]
}
}

Create a dashboard

Creates a dashboard with a specified name.

URL

POST /api/v1/dashboards

Sample request

Show sample request
curl -X POST 'http://PIVOT_URL/api/v1/dashboards' \
--header 'x-imply-api-token: <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"dashboard": {
"name": "Wikipedia_Top7_europe",
"title": "Wikipedia: Top 7 european countries",
"type": "dashboard2",
"readAccess": {
"access": "all"
},
"modifyAccess": {
"access": "single",
"users": [
"analyst@example.com"
]
},
"pages": [
{
"name": "page",
"label": "New page",
"tiles": [
{
"name": "t8075",
"type": "visualization",
"title": "Europe top 5",
"canExpand": true,
"description": "Number of events for the top 5 European countries",
"position": {
"width": 5,
"height": 5,
"y": 3
},
"facetEssence": {
"dataCube": "wikipedia00e7",
"timezone": "Etc/UTC",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"dynamic": {
"op": "timeRange",
"operand": {
"op": "ref",
"name": "m"
},
"duration": "P1D",
"step": -1
}
},
{
"dimension": "countryName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"United Kingdom",
"Germany",
"Spain",
"Italy",
"France"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"axesSplits": [
[
{
"dimension": "countryName",
"sortType": "measure",
"direction": "descending"
}
]
],
"visualization": "pie-chart",
"selectedMeasures": [
{
"measure": "count"
}
],
"pinnedDimensions": []
}
},
{
"name": "te111",
"type": "markdown",
"title": "Introduction",
"titleHidden": true,
"canExpand": true,
"description": "Introductory markdown tile",
"position": {
"width": 5,
"height": 3
},
"content": "## Wikipedia: General\n\nGeneral [Wikipedia](https://en.wikipedia.org/) dashboard showing:\n\n- Events for top 5 European cities\n"
}
]
}
]
}
}'

Success response

CodeDescription
200"status": "ok"

Sample error response

CodeExample body
400 Bad Request"err": "Er.name 'Wikipedia: Top 5 europe' is not a URL safe name. Try 'Wikipedia-_Top_5_europe' instead?"

Sample response

Show sample response
{
"status": "ok",
"message": "Created successfully",
"dashboard": {
"name": "Wikipedia_Top5_europe",
"title": "Wikipedia: Top 5 european countries",
"type": "dashboard2",
"readAccess": {
"access": "all"
},
"modifyAccess": {
"access": "single",
"users": [
"analyst@example.com"
]
},
"pages": [
{
"name": "page",
"label": "New page",
"tiles": [
{
"name": "t8075",
"type": "visualization",
"title": "Europe top 5",
"canExpand": true,
"description": "Number of events for the top 5 European countries",
"position": {
"width": 5,
"height": 5,
"y": 3
},
"facetEssence": {
"dataCube": "wikipedia00e7",
"timezone": "Etc/UTC",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"dynamic": {
"op": "timeRange",
"operand": {
"op": "ref",
"name": "m"
},
"duration": "P1D",
"step": -1
}
},
{
"dimension": "countryName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"United Kingdom",
"Germany",
"Spain",
"Italy",
"France"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"axesSplits": [
[
{
"dimension": "countryName",
"sortType": "measure",
"direction": "descending"
}
]
],
"visualization": "pie-chart",
"selectedMeasures": [
{
"measure": "count"
}
],
"pinnedDimensions": []
}
},
{
"name": "te111",
"type": "markdown",
"title": "Introduction",
"titleHidden": true,
"canExpand": true,
"description": "Introductory markdown tile",
"position": {
"width": 5,
"height": 3
},
"content": "## Wikipedia: General\n\nGeneral [Wikipedia](https://en.wikipedia.org/) dashboard showing:\n\n- Events for top 5 European cities\n"
}
]
}
]
}
}

Update a dashboard

Updates the details of a dashboard with a specified name. Note that the dashboard name is not the same as the name that appears in the Pivot UI. Get all dashboards to find a dashboard name.

URL

POST /api/v1/dashboards/{name}

Sample request

The following example request updates the dashboard title and removes all tiles except the pie chart visualization with "name":"t8075".

You must provide all properties you want to retain in the dashboard, even if you don't want to update them. Pivot recreates the dashboard with the details you specify in the request.

Show sample request
curl -X POST 'http://PIVOT_URL/api/v1/dashboards/Wikipedia_Top5_europe' \
--header 'x-imply-api-token: <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"dashboard": {
"name": "Wikipedia_Top5_europe",
"title": "Wikipedia: Events for top 5 european countries",
"type": "dashboard2",
"readAccess": {
"access": "all"
},
"modifyAccess": {
"access": "single",
"users": [
"analyst@example.com"
]
},
"pages": [
{
"name": "page",
"label": "New page",
"tiles": [
{
"name": "t8075",
"type": "visualization",
"title": "Europe top 5",
"canExpand": true,
"description": "Number of events for the top 5 European countries",
"position": {
"width": 5,
"height": 5
},
"facetEssence": {
"dataCube": "wikipedia00e7",
"timezone": "Etc/UTC",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"dynamic": {
"op": "timeRange",
"operand": {
"op": "ref",
"name": "m"
},
"duration": "P1D",
"step": -1
}
},
{
"dimension": "countryName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"United Kingdom",
"Germany",
"Spain",
"Italy",
"France"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"axesSplits": [
[
{
"dimension": "countryName",
"sortType": "measure",
"direction": "descending"
}
]
],
"visualization": "pie-chart",
"selectedMeasures": [
{
"measure": "count"
}
],
"pinnedDimensions": []
}
}
]
}
]
}
}'

Success response

CodeDescription
200"status": "ok"

Sample error response

CodeExample body
400 Bad Request”error": "the name you entered does not match"
Show sample response
### Sample response
{
"status": "ok",
"message": "Updated successfully",
"dashboard": {
"name": "Wikipedia_Top5_europe",
"title": "Wikipedia: Events for top 5 european countries",
"type": "dashboard2",
"readAccess": {
"access": "all"
},
"modifyAccess": {
"access": "single",
"users": [
"analyst@example.com"
]
},
"pages": [
{
"name": "page",
"label": "New page",
"tiles": [
{
"name": "t8075",
"type": "visualization",
"title": "Europe top 5",
"canExpand": true,
"description": "Number of events for the top 5 European countries",
"position": {
"width": 5,
"height": 5
},
"facetEssence": {
"dataCube": "wikipedia00e7",
"timezone": "Etc/UTC",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"dynamic": {
"op": "timeRange",
"operand": {
"op": "ref",
"name": "m"
},
"duration": "P1D",
"step": -1
}
},
{
"dimension": "countryName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"United Kingdom",
"Germany",
"Spain",
"Italy",
"France"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"axesSplits": [
[
{
"dimension": "countryName",
"sortType": "measure",
"direction": "descending"
}
]
],
"visualization": "pie-chart",
"selectedMeasures": [
{
"measure": "count"
}
],
"pinnedDimensions": []
}
}
]
}
]
}
}

Delete a dashboard

Deletes a dashboard with a specified name.

URL

DELETE /api/v1/dashboards/{name}

Sample request

curl -X DELETE 'http://PIVOT_URL/api/v1/dashboards/Wikipedia_Top5_europe' \
--header 'x-imply-api-token:<token>'

Success response

CodeDescription
200"status": "ok"

Sample error response

CodeExample body
404 Not Found"error": "This dashboard does not exist. Please check the name again."

Sample response

{
"status": "ok",
"message": "Deleted successfully"
}