Pivot reports API
You can use the Pivot reports API to create, read, and modify reports.
Pivot must be running in native users mode.
Get all reports
Returns a list of all reports.
URL
GET /api/v1/reports
Success response
| Code | Description |
|---|---|
| 200 | "status": "ok" |
Sample request
curl -X GET 'http://PIVOT_URL/api/v1/reports' \
--header 'x-imply-api-token:<token>'
Sample success response
Click for sample success response
{
"reports": [
{
"name": "d7ba",
"owner": "admin@example.com",
"creationDate": "2023-01-31T13:55:09.772Z",
"title": "Daily Wikipedia report: Chicago",
"description": "Events for #en.wikipedia channel from Chicago",
"delivery": {
"frequency": "P1D",
"day": 1,
"time": 9,
"dayType": "of-week",
"frequencyType": "fixed"
},
"timeFrame": {
"interval": "previous_day",
"startDay": 0,
"startTime": 9
},
"essence": {
"dataCube": "wikipedia3c4f",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"values": {
"setType": "TIME_RANGE",
"elements": [
{
"start": "2016-06-26T21:32:00.000Z",
"end": "2016-06-27T21:32:00.000Z"
}
]
}
},
{
"dimension": "channel",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"#en.wikipedia"
]
},
"exclude": false,
"mvFilterOnly": false
},
{
"dimension": "cityName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"Chicago"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"splits": [
{
"dimension": "countryName",
"sortType": "measure",
"direction": "descending"
},
{
"dimension": "cityName",
"sortType": "measure",
"direction": "descending"
},
{
"dimension": "comment",
"sortType": "measure",
"direction": "descending"
}
],
"selectedMeasures": [
"count"
],
"pinnedDimensions": [],
"timezone": "Etc/UTC",
"visualization": "table",
"compare": {
"type": "relative",
"duration": "P1D"
}
},
"readAccess": {
"access": "specific"
},
"recipients": {
"access": "single",
"users": [
"admin@example.com"
]
},
"admins": {
"access": "single",
"users": [
"admin@example.com"
]
},
"externalEmails": [],
"preferredView": "pivot2"
},
{
"name": "be81",
"owner": "analyst@example.com",
"creationDate": "2023-01-28T14:03:02.924Z",
"title": "Weekly Wikipedia report: New York",
"description": "Events for all channels from New York",
"delivery": {
"frequency": "P1W",
"day": 1,
"time": 9,
"dayType": "of-week",
"frequencyType": "fixed"
},
"timeFrame": {
"interval": "previous_week",
"startDay": 0,
"startTime": 0
},
"essence": {
"dataCube": "wikipedia3c4f",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"dynamic": {
"op": "timeRange",
"operand": {
"op": "ref",
"name": "m"
},
"duration": "P1D",
"step": -1
}
},
{
"dimension": "cityName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"New York"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"splits": [
{
"dimension": "channel",
"sortType": "measure",
"direction": "descending"
},
{
"dimension": "comment",
"sortType": "measure",
"direction": "descending"
}
],
"selectedMeasures": [
"count"
],
"pinnedDimensions": [],
"timezone": "Etc/UTC",
"visualization": "table",
"auxiliaryMeasures": []
},
"readAccess": {
"access": "specific"
},
"recipients": {
"access": "single",
"users": [
"admin@example.com"
]
},
"admins": {
"access": "single",
"users": [
"admin@example.com"
]
},
"externalEmails": [],
"preferredView": "pivot1"
}
]
}
Get a report
Returns a report with a specified name.
URL
GET /api/v1/reports/{name}
Success response
| Code | Description |
|---|---|
| 200 | "status": "ok" |
Sample error response
| Code | Example body |
|---|---|
| 404 Not Found | "error": "This report does not exist." |
Sample request
curl -X GET 'http://PIVOT_URL/api/v1/reports/be81' \
--header 'x-imply-api-token:<token>'
Sample success response
Click for sample success response
{
"report": {
"name": "be81",
"owner": "analyst@example.com",
"creationDate": "2023-01-28T14:03:02.924Z",
"title": "Weekly Wikipedia report: New York",
"description": "Events for all channels from New York",
"delivery": {
"frequency": "P1W",
"day": 1,
"time": 9,
"dayType": "of-week",
"frequencyType": "fixed"
},
"timeFrame": {
"interval": "previous_week",
"startDay": 0,
"startTime": 0
},
"essence": {
"dataCube": "wikipedia3c4f",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"dynamic": {
"op": "timeRange",
"operand": {
"op": "ref",
"name": "m"
},
"duration": "P1D",
"step": -1
}
},
{
"dimension": "cityName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"New York"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"splits": [
{
"dimension": "channel",
"sortType": "measure",
"direction": "descending"
},
{
"dimension": "comment",
"sortType": "measure",
"direction": "descending"
}
],
"selectedMeasures": [
"count"
],
"pinnedDimensions": [],
"timezone": "Etc/UTC",
"visualization": "table",
"auxiliaryMeasures": []
},
"readAccess": {
"access": "specific"
},
"recipients": {
"access": "single",
"users": [
"analyst@example.com"
]
},
"admins": {
"access": "single",
"users": [
"analyst@example.com"
]
},
"externalEmails": [],
"preferredView": "pivot1"
}
}
Create a report
Creates a report with a specified name.
URL
POST /api/v1/reports
Sample request
Click for sample request
curl -X POST 'http://PIVOT_URL/api/v1/reports' \
--header 'x-imply-api-token: <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"report": {
"name": "Daily Chicago Report",
"owner": "admin@example.com",
"creationDate": "2023-01-31T13:55:09.772Z",
"title": "Daily Wikipedia report: Chicago",
"description": "Events for #en.wikipedia channel from Chicago",
"delivery": {
"frequency": "P1D",
"day": 1,
"time": 9,
"dayType": "of-week",
"frequencyType": "fixed"
},
"timeFrame": {
"interval": "previous_day",
"startDay": 0,
"startTime": 9
},
"essence": {
"dataCube": "wikipedia3c4f",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"values": {
"setType": "TIME_RANGE",
"elements": [
{
"start": "2016-06-26T21:32:00.000Z",
"end": "2016-06-27T21:32:00.000Z"
}
]
}
},
{
"dimension": "channel",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"#en.wikipedia"
]
},
"exclude": false,
"mvFilterOnly": false
},
{
"dimension": "cityName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"Chicago"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"splits": [
{
"dimension": "countryName",
"sortType": "measure",
"direction": "descending"
},
{
"dimension": "cityName",
"sortType": "measure",
"direction": "descending"
},
{
"dimension": "comment",
"sortType": "measure",
"direction": "descending"
}
],
"selectedMeasures": [
"count"
],
"pinnedDimensions": [],
"timezone": "Etc/UTC",
"visualization": "table",
"compare": {
"type": "relative",
"duration": "P1D"
}
},
"readAccess": {
"access": "specific"
},
"recipients": {
"access": "single",
"users": [
"admin@example.com"
]
},
"admins": {
"access": "single",
"users": [
"admin@example.com"
]
},
"externalEmails": [],
"preferredView": "pivot2"
}
}'
Success response
| Code | Description |
|---|---|
| 200 | "status": "ok" |
Sample error response
| Code | Example body |
|---|---|
| 400 Bad Request | "error": "owner must be defined" |
Sample success response
Click for sample success response
{
"status": "ok",
"message": "Created successfully",
"report": {
"name": "Daily Chicago Report",
"owner": "admin@example.com",
"creationDate": "2023-01-31T13:55:09.772Z",
"title": "Daily Wikipedia report: Chicago",
"description": "Events for #en.wikipedia channel from Chicago",
"delivery": {
"frequency": "P1D",
"day": 1,
"time": 9,
"dayType": "of-week",
"frequencyType": "fixed"
},
"timeFrame": {
"interval": "previous_day",
"startDay": 0,
"startTime": 9
},
"essence": {
"dataCube": "wikipedia3c4f",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"values": {
"setType": "TIME_RANGE",
"elements": [
{
"start": "2016-06-26T21:32:00.000Z",
"end": "2016-06-27T21:32:00.000Z"
}
]
}
},
{
"dimension": "channel",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"#en.wikipedia"
]
},
"exclude": false,
"mvFilterOnly": false
},
{
"dimension": "cityName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"Chicago"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"splits": [
{
"dimension": "countryName",
"sortType": "measure",
"direction": "descending"
},
{
"dimension": "cityName",
"sortType": "measure",
"direction": "descending"
},
{
"dimension": "comment",
"sortType": "measure",
"direction": "descending"
}
],
"selectedMeasures": [
"count"
],
"pinnedDimensions": [],
"timezone": "Etc/UTC",
"visualization": "table",
"compare": {
"type": "relative",
"duration": "P1D"
}
},
"readAccess": {
"access": "specific"
},
"recipients": {
"access": "single",
"users": [
"admin@example.com"
]
},
"admins": {
"access": "single",
"users": [
"admin@example.com"
]
},
"externalEmails": [],
"preferredView": "pivot2"
}
}
Update a report
Updates the details of a report with a specified name.
URL
POST /api/v1/reports/{name}
Sample request
The following example request updates the owner and title properties of the Daily Chicago Report report object. The name in the request body must match the {name} in the URL. You can't update the name field.
At a minimum, you must provide name, owner, and creationDate in the report body. You must provide all report properties you want to retain in the report, even if you don't want to update them. Pivot recreates the report with the details you specify in the request.
Click for sample request
curl -X POST 'http://PIVOT_URL/api/v1/reports/Daily Chicago Report' \
--header 'x-imply-api-token: <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
"report": {
"name": "Daily Chicago Report",
"owner": "analyst@example.com",
"creationDate": "2023-01-31T13:55:09.772Z",
"title": "Daily Wikipedia report: Chicago #en.wikipedia events",
"description": "Events for #en.wikipedia channel from Chicago",
"delivery": {
"frequency": "P1D",
"day": 1,
"time": 9,
"dayType": "of-week",
"frequencyType": "fixed"
},
"timeFrame": {
"interval": "previous_day",
"startDay": 0,
"startTime": 9
},
"essence": {
"dataCube": "wikipedia3c4f",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"values": {
"setType": "TIME_RANGE",
"elements": [
{
"start": "2016-06-26T21:32:00.000Z",
"end": "2016-06-27T21:32:00.000Z"
}
]
}
},
{
"dimension": "channel",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"#en.wikipedia"
]
},
"exclude": false,
"mvFilterOnly": false
},
{
"dimension": "cityName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"Chicago"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"splits": [
{
"dimension": "countryName",
"sortType": "measure",
"direction": "descending"
},
{
"dimension": "cityName",
"sortType": "measure",
"direction": "descending"
},
{
"dimension": "comment",
"sortType": "measure",
"direction": "descending"
}
],
"selectedMeasures": [
"count"
],
"pinnedDimensions": [],
"timezone": "Etc/UTC",
"visualization": "table",
"compare": {
"type": "relative",
"duration": "P1D"
}
},
"readAccess": {
"access": "specific"
},
"recipients": {
"access": "single",
"users": [
"analyst@example.com"
]
},
"admins": {
"access": "single",
"users": [
"analyst@example.com"
]
},
"externalEmails": [],
"preferredView": "pivot2"
}
}'
Success response
| Code | Description |
|---|---|
| 200 | "status": "ok" |
Sample error response
| Code | Example body |
|---|---|
| 400 Bad Request | "error": "the name you entered does not match" |
Sample success response
Click for sample success response
{
"status": "ok",
"message": "Updated successfully",
"report": {
"name": "Daily Chicago Report",
"owner": "analyst@example.com",
"creationDate": "2023-01-31T13:55:09.772Z",
"title": "Daily Wikipedia report: Chicago #en.wikipedia events",
"description": "Events for #en.wikipedia channel from Chicago",
"delivery": {
"frequency": "P1D",
"day": 1,
"time": 9,
"dayType": "of-week",
"frequencyType": "fixed"
},
"timeFrame": {
"interval": "previous_day",
"startDay": 0,
"startTime": 9
},
"essence": {
"dataCube": "wikipedia3c4f",
"filter": {
"clauses": [
{
"dimension": "__time",
"action": "overlap",
"values": {
"setType": "TIME_RANGE",
"elements": [
{
"start": "2016-06-26T21:32:00.000Z",
"end": "2016-06-27T21:32:00.000Z"
}
]
}
},
{
"dimension": "channel",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"#en.wikipedia"
]
},
"exclude": false,
"mvFilterOnly": false
},
{
"dimension": "cityName",
"action": "overlap",
"values": {
"setType": "STRING",
"elements": [
"Chicago"
]
},
"exclude": false,
"mvFilterOnly": false
}
]
},
"splits": [
{
"dimension": "countryName",
"sortType": "measure",
"direction": "descending"
},
{
"dimension": "cityName",
"sortType": "measure",
"direction": "descending"
},
{
"dimension": "comment",
"sortType": "measure",
"direction": "descending"
}
],
"selectedMeasures": [
"count"
],
"pinnedDimensions": [],
"timezone": "Etc/UTC",
"visualization": "table",
"compare": {
"type": "relative",
"duration": "P1D"
}
},
"readAccess": {
"access": "specific"
},
"recipients": {
"access": "single",
"users": [
"analyst@example.com"
]
},
"admins": {
"access": "single",
"users": [
"analyst@example.com"
]
},
"externalEmails": [],
"preferredView": "pivot2"
}
}
Delete a report
Deletes a report with a specified name.
URL
DELETE /api/v1/reports/{name}
Sample request
curl -X DELETE 'http://PIVOT_URL/api/v1/reports/Daily Chicago Report' \
--header 'x-imply-api-token:<token>'
Success response
| Code | Description |
|---|---|
| 200 | "status": "ok" |
Sample error response
| Code | Example body |
|---|---|
| 404 Not Found | "error": "This report does not exist. Please check the name again." |
Sample success response
{
"status": "ok",
"message": "Deleted successfully"
}