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
| Code | Description |
|---|---|
| 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
| Code | Description |
|---|---|
| 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
| Code | Description |
|---|---|
| 200 | "status": "ok" |
Sample error response
| Code | Example 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
| Code | Description |
|---|---|
| 200 | "status": "ok" |
Sample error response
| Code | Example 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
| Code | Description |
|---|---|
| 200 | "status": "ok" |
Sample error response
| Code | Example body |
|---|---|
| 404 Not Found | "error": "This dashboard does not exist. Please check the name again." |
Sample response
{
"status": "ok",
"message": "Deleted successfully"
}