2023.03

2023.03

  • Imply
  • Ingest
  • Query
  • Visualize
  • Administer
  • Deploy

›Pivot API

Overview

  • Pivot overview
  • Datasources
  • SQL

Data cubes

  • About data cubes
  • Managing data cubes
  • Visualizations
  • Dimensions
  • Measures
  • Custom dimensions and measures
  • Time compare
  • Filter by measure
  • Annotations
  • Data export

Dashboards

  • Viewing dashboards
  • Creating dashboards
  • Managing dashboards

Alerts & Reports

  • Alerts
  • Scheduled reports

User access

  • Access control
  • User management in Pivot
  • Manage users with LDAP
  • Manage users with OIDC

Advanced features

  • Feature Flags
  • Customizing the Pivot UI
  • Generating links into Pivot
  • Monitor queries
  • Explain
  • CrossTab
  • Pivot server config
  • Plywood Expressions
  • Query parameters reference

Pivot API

  • Pivot API overview
  • Pivot alerts API
  • Pivot connections API
  • Pivot dashboards API
  • Pivot data cubes API
  • Pivot reports API
  • Pivot roles API
  • Pivot user auths API
  • Pivot user statuses API
  • Pivot users API

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

CodeDescription
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

CodeDescription
200"status": "ok"

Sample error response

CodeExample 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

CodeDescription
200"status": "ok"

Sample error response

CodeExample 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

CodeDescription
200"status": "ok"

Sample error response

CodeExample 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

CodeDescription
200"status": "ok"

Sample error response

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

Sample success response

{
    "status": "ok",
    "message": "Deleted successfully"
}
Last updated on 2/16/2023
← Pivot data cubes APIPivot roles API →
  • Get all reports
    • URL
    • Success response
    • Sample request
    • Sample success response
  • Get a report
    • URL
    • Success response
    • Sample error response
    • Sample request
    • Sample success response
  • Create a report
    • URL
    • Sample request
    • Success response
    • Sample error response
    • Sample success response
  • Update a report
    • URL
    • Sample request
    • Success response
    • Sample error response
    • Sample success response
  • Delete a report
    • URL
    • Sample request
    • Success response
    • Sample error response
    • Sample success response
2023.03
Key links
Try ImplyApache Druid siteImply GitHub
Get help
Stack OverflowSupportContact us
Learn more
Apache Druid forumsBlog
Copyright © 2023 Imply Data, Inc