2022-05-26 16:06:25 +01:00
---
aliases :
2022-12-09 12:36:04 -04:00
- ../../http_api/reporting/
2023-02-06 17:14:36 +00:00
canonical : /docs/grafana/latest/developers/http_api/reporting/
2022-05-26 16:06:25 +01:00
description : Grafana Enterprise APIs
keywords :
- grafana
- enterprise
- api
- reporting
2023-07-18 09:10:12 +01:00
labels :
products :
- enterprise
- oss
2022-05-26 16:06:25 +01:00
title : Reporting API
---
2020-05-06 09:28:33 +02:00
# Reporting API
2023-03-15 17:06:31 +00:00
This API allows you to interact programmatically with the [Reporting ]({{< relref "/docs/grafana/latest/dashboards/create-reports" >}} ) feature.
2020-05-06 09:28:33 +02:00
2022-09-28 17:03:43 +02:00
> The Reporting API is not stabilized yet, it is still in active development and may change without prior notice.
2023-03-15 17:06:31 +00:00
> Reporting is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "/docs/grafana/latest/introduction/grafana-enterprise" >}}).
2020-05-06 09:28:33 +02:00
2023-03-15 17:06:31 +00:00
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes" >}}) for more information.
2021-08-06 07:52:36 -06:00
2022-09-28 17:03:43 +02:00
## List all reports
`GET /api/reports`
#### Required permissions
2023-03-15 17:06:31 +00:00
See note in the [introduction ]({{< relref "#reporting-api" >}} ) for an explanation.
2022-09-28 17:03:43 +02:00
| Action | Scope |
| ------------ | --------------------------- |
| reports:read | reports:\*<br>reports:id:\* |
### Example request
```http
GET /api/reports HTTP / 1.1
Accept : application/json
Content-Type : application/json
Authorization : Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
2020-05-06 09:28:33 +02:00
2022-09-28 17:03:43 +02:00
### Example response
```http
HTTP / 1.1 200 OK
Content-Type : application/json
Content-Length : 1840
[
{
"id" : 2 ,
"userId" : 1 ,
"orgId" : 1 ,
"name" : "Report 2" ,
"recipients" : "example-report@grafana.com" ,
"replyTo" : "" ,
"message" : "Hi, \nPlease find attached a PDF status report. If you have any questions, feel free to contact me!\nBest," ,
"schedule" : {
"startDate" : "2022-10-02T00:00:00+02:00" ,
"endDate" : null ,
"frequency" : "once" ,
"intervalFrequency" : "" ,
"intervalAmount" : 0 ,
"workdaysOnly" : false ,
"dayOfMonth" : "2" ,
"timeZone" : "Europe/Warsaw"
},
"options" : {
"orientation" : "landscape" ,
"layout" : "grid" ,
},
"enableDashboardUrl" : true ,
"state" : "scheduled" ,
"dashboards" : [
{
"dashboard" : {
"id" : 463 ,
"uid" : "7MeksYbmk" ,
"name" : "Alerting with TestData"
},
"reportVariables" : {
"namefilter" : "TestData"
}
}
],
"formats" : [
"pdf" ,
"csv"
],
"created" : "2022-09-19T11:44:42+02:00" ,
"updated" : "2022-09-19T11:44:42+02:00"
}
]
```
### Status Codes
- **200** – OK
2023-03-15 17:06:31 +00:00
- **401** - Authentication failed, refer to [Authentication API ]({{< relref "/docs/grafana/latest/developers/http_api/auth" >}} ).
2022-09-28 17:03:43 +02:00
- **500** – Unexpected error or server misconfiguration. Refer to server logs for more details.
## Get a report
`GET /api/reports/:id`
#### Required permissions
2023-03-15 17:06:31 +00:00
See note in the [introduction ]({{< relref "#reporting-api" >}} ) for an explanation.
2020-05-06 09:28:33 +02:00
2022-09-28 17:03:43 +02:00
| Action | Scope |
| ------------ | ---------------------------------------------------------- |
| reports:read | reports:\*<br>reports:id:\*<br>reports:id:1(single report) |
### Example request
```http
GET /api/reports/2 HTTP / 1.1
Accept : application/json
Content-Type : application/json
Authorization : Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
### Example response
```http
HTTP / 1.1 200 OK
Content-Type : application/json
Content-Length : 940
{
"id" : 2 ,
"userId" : 1 ,
"orgId" : 1 ,
"name" : "Report 2" ,
"recipients" : "example-report@grafana.com" ,
"replyTo" : "" ,
"message" : "Hi, \nPlease find attached a PDF status report. If you have any questions, feel free to contact me!\nBest," ,
"schedule" : {
"startDate" : "2022-10-02T00:00:00+02:00" ,
"endDate" : null ,
"frequency" : "once" ,
"intervalFrequency" : "" ,
"intervalAmount" : 0 ,
"workdaysOnly" : false ,
"dayOfMonth" : "2" ,
"timeZone" : "Europe/Warsaw"
},
"options" : {
"orientation" : "landscape" ,
"layout" : "grid" ,
},
"enableDashboardUrl" : true ,
"state" : "scheduled" ,
"dashboards" : [
{
"dashboard" : {
"id" : 463 ,
"uid" : "7MeksYbmk" ,
"name" : "Alerting with TestData"
},
"timeRange" : {
"from" : "" ,
"to" : ""
},
"reportVariables" : {
"namefilter" : "TestData"
}
}
],
"formats" : [
"pdf" ,
"csv"
],
"created" : "2022-09-12T11:44:42+02:00" ,
"updated" : "2022-09-12T11:44:42+02:00"
}
```
### Status Codes
- **200** – OK
- **400** – Bad request (invalid report ID).
2023-03-15 17:06:31 +00:00
- **401** - Authentication failed, refer to [Authentication API ]({{< relref "/docs/grafana/latest/developers/http_api/auth" >}} ).
2022-09-28 17:03:43 +02:00
- **403** – Forbidden (access denied to a report or a dashboard used in the report).
- **404** – Not found (such report does not exist).
- **500** – Unexpected error or server misconfiguration. Refer to server logs for more details.
## Create a report
`POST /api/reports`
#### Required permissions
See note in the [introduction ]({{< ref "#reporting-api" >}} ) for an explanation.
| Action | Scope |
| -------------- | ----- |
| reports:create | n/a |
### Example request
```http
POST /api/reports HTTP / 1.1
Accept : application/json
Content-Type : application/json
Authorization : Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"name" : "Report 4" ,
"recipients" : "texample-report@grafana.com" ,
"replyTo" : "" ,
"message" : "Hello, please, find the report attached" ,
"schedule" : {
"startDate" : "2022-10-02T10:00:00+02:00" ,
"endDate" : "2022-11-02T20:00:00+02:00" ,
"frequency" : "daily" ,
"intervalFrequency" : "" ,
"intervalAmount" : 0 ,
"workdaysOnly" : true ,
"timeZone" : "Europe/Warsaw"
},
"options" : {
"orientation" : "landscape" ,
"layout" : "grid"
},
"enableDashboardUrl" : true ,
"dashboards" : [
{
"dashboard" : {
"uid" : "7MeksYbmk" ,
},
"timeRange" : {
"from" : "2022-08-08T15:00:00+02:00" ,
"to" : "2022-09-02T17:00:00+02:00"
},
"reportVariables" : {
2024-02-26 12:52:44 -05:00
"variable1" : "Value1"
2022-09-28 17:03:43 +02:00
}
}
],
"formats" : [
"pdf" ,
"csv"
]
}
```
#### Config JSON Body Schema
| Field name | Data type | Description |
| ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | Name of the report that is used as an email subject. |
| recipients | string | Comma-separated list of emails to which to send the report to. |
| replyTo | string | Comma-separated list of emails used in a reply-to field of the report email. |
| message | string | Text message used for the body of the report email. |
| startDate | string | Report distribution starts from this date. |
| endDate | string | Report distribution ends on this date. |
| frequency | string | Specifies how often the report should be sent. Can be `once` , `hourly` , `daily` , `weekly` , `monthly` , `last` or `custom` .<br/><br/>`last` - schedules the report for the last day of month.<br/><br/>`custom` - schedules the report to be sent on a custom interval.<br/>It requires `intervalFrequency` and `intervalAmount` to be specified: for example, every 2 weeks, where 2 is an `intervalAmount` and `weeks` is an `intervalFrequency` . |
| intervalFrequency | string | The type of the `custom` interval: `hours` , `days` , `weeks` , `months` . |
| intervalAmount | number | `custom` interval amount. |
| workdaysOnly | string | Send the report only on Monday-Friday. Applicable to `hourly` and `daily` types of schedule. |
| timeZone | string | Time zone used to schedule report execution. |
| orientation | string | Can be `portrait` or `landscape` . |
| layout | string | Can be `grid` or `simple` . |
| enableDashboardUrl | bool | Adds a dashboard url to the bottom of the report email. |
| formats | []string | Specified what kind of attachment to generate for the report - `csv` , `pdf` , `image` .<br/>`pdf` is the default one.<br/>`csv` attaches a CSV file for each table panel.<br/>`image` embeds an image of a dashboard into the email's body. |
| dashboards | []object | Dashboards to generate a report for.<br/> See "Report Dashboard Schema" section below. |
#### Report Dashboard Schema
| Field name | Data type | Description |
| ------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| dashboard.uid | string | Dashboard [UID ](../dashboard#identifier-id-vs-unique-identifier-uid ). |
| timeRange.from | string | Dashboard time range from. |
| timeRange.to | string | Dashboard time range to. |
| reportVariables.<variableName> | string | Key-value pairs containing the template variables for this report, in JSON format. If empty, the template variables from the report's dashboard will be used. |
### Example response
```http
HTTP / 1.1 200 OK
Content-Type : application/json
Content-Length : 35
{
"id" : 4 ,
"message" : "Report created"
}
```
### Status Codes
- **200** – OK
- **400** – Bad request (invalid json, missing or invalid fields values, etc.).
- **403** - Forbidden (access denied to a report or a dashboard used in the report).
- **500** - Unexpected error or server misconfiguration. Refer to server logs for more details
## Update a report
`PUT /api/reports/:id`
#### Required permissions
See note in the [introduction ]({{< ref "#reporting-api" >}} ) for an explanation.
| Action | Scope |
| ------------- | --------------------------------------------------------- |
| reports:write | reports:\*</br>reports:id:\*</br>reports:1(single report) |
### Example request
See [JSON body schema ]({{< ref "#config-json-body-schema" >}} ) for fields description.
```http
GET /api/reports HTTP / 1.1
Accept : application/json
Content-Type : application/json
Authorization : Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"name" : "Updated Report" ,
"recipients" : "example-report@grafana.com" ,
"replyTo" : "" ,
"message" : "Hello, please, find the report attached" ,
"schedule" : {
"frequency" : "hourly" ,
"timeZone" : "Africa/Cairo" ,
"workdaysOnly" : true ,
"startDate" : "2022-10-10T10:00:00+02:00" ,
"endDate" : "2022-11-20T19:00:00+02:00"
},
"options" : {
"orientation" : "landscape" ,
"layout" : "grid" ,
},
"enableDashboardUrl" : true ,
"state" : "scheduled" ,
"dashboards" : [
{
"dashboard" : {
"id" : 463 ,
"uid" : "7MeksYbmk" ,
"name" : "Alerting with TestData"
},
"timeRange" : {
"from" : "2022-08-08T15:00:00+02:00" ,
"to" : "2022-09-02T17:00:00+02:00"
},
"reportVariables" : {
2024-02-05 20:46:35 +01:00
"variable1" : "Value1"
2022-09-28 17:03:43 +02:00
}
}
],
"formats" : [
"pdf" ,
"csv"
]
}
```
### Example response
```http
HTTP / 1.1 200 OK
Content-Type : application/json
Content-Length : 28
{
"message" : "Report updated"
}
```
### Status Codes
- **200** – OK
- **400** – Bad request (invalid json, missing or invalid fields values, etc.).
2023-03-15 17:06:31 +00:00
- **401** - Authentication failed, refer to [Authentication API ]({{< relref "/docs/grafana/latest/developers/http_api/auth" >}} ).
2022-09-28 17:03:43 +02:00
- **403** – Forbidden (access denied to a report or a dashboard used in the report).
- **404** – Not found (such report does not exist).
- **500** – Unexpected error or server misconfiguration. Refer to server logs for more details.
## Delete a report
`DELETE /api/reports/:id`
#### Required permissions
See note in the [introduction ]({{< ref "#reporting-api" >}} ) for an explanation.
| Action | Scope |
| -------------- | --------------------------------------------------------- |
| reports:delete | reports:\*</br>reports:id:\*</br>reports:1(single report) |
### Example request
```http
GET /api/reports/6 HTTP / 1.1
Accept : application/json
Content-Type : application/json
Authorization : Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
### Example response
```http
HTTP / 1.1 200 OK
Content-Type : application/json
Content-Length : 39
{
"message" : "Report config was removed"
}
```
### Status Codes
- **200** – OK
- **400** – Bad request (invalid report ID).
2023-03-15 17:06:31 +00:00
- **401** - Authentication failed, refer to [Authentication API ]({{< relref "/docs/grafana/latest/developers/http_api/auth" >}} ).
2022-09-28 17:03:43 +02:00
- **404** - Not found (report with this ID does not exist).
- **500** - Unexpected error or server misconfiguration. Refer to server logs for more details
## Send a report
2020-05-06 09:28:33 +02:00
`POST /api/reports/email`
Generate and send a report. This API waits for the report to be generated before returning. We recommend that you set the client's timeout to at least 60 seconds.
2021-05-20 18:53:34 +02:00
#### Required permissions
See note in the [introduction ]({{< ref "#reporting-api" >}} ) for an explanation.
2021-08-06 07:52:36 -06:00
| Action | Scope |
| ------------ | ----- |
| reports:send | n/a |
2021-05-20 18:53:34 +02:00
2020-05-06 09:28:33 +02:00
### Example request
```http
POST /api/reports/email HTTP / 1.1
Accept : application/json
Content-Type : application/json
Authorization : Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"id" : "3" ,
"useEmailsFromReport" : true
}
```
2022-09-28 17:03:43 +02:00
#### JSON Body Schema
2020-05-06 09:28:33 +02:00
2022-09-28 17:03:43 +02:00
| Field name | Data type | Description |
| ------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| id | string | ID of the report to send. It is the same as in the URL when editing a report, not to be confused with the ID of the dashboard. Required. |
| emails | string | Comma-separated list of emails to which to send the report to. Overrides the emails from the report. Required if `useEmailsFromReport` is not present. |
| useEmailsFromReport | boolean | Send the report to the emails specified in the report. Required if `emails` is not present. |
2020-05-06 09:28:33 +02:00
### Example response
```http
HTTP / 1.1 200 OK
Content-Type : application/json
Content-Length : 29
{ "message" : "Report was sent" }
```
### Status Codes
2022-09-28 17:03:43 +02:00
- **200** – Report was sent.
- **400** – Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
2023-03-15 17:06:31 +00:00
- **401** - Authentication failed, refer to [Authentication API ]({{< relref "/docs/grafana/latest/developers/http_api/auth" >}} ).
2022-09-28 17:03:43 +02:00
- **403** - Forbidden (access denied to a report or a dashboard used in the report).
- **404** - Report not found.
- **500** - Unexpected error or server misconfiguration. Refer to server logs for more details.
## Get reports branding settings
`GET /api/reports/settings`
Returns reports branding settings that are global and used across all the reports.
#### Required permissions
See note in the [introduction ]({{< ref "#reporting-api" >}} ) for an explanation.
| Action | Scope |
| --------------------- | ----- |
| reports.settings:read | n/a |
### Example request
```http
GET /api/reports/settings HTTP / 1.1
Accept : application/json
Content-Type : application/json
Authorization : Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
### Example response
```http
HTTP / 1.1 200 OK
Content-Type : application/json
Content-Length : 181
{
"id" : 1 ,
"userId" : 1 ,
"orgId" : 1 ,
"branding" : {
"reportLogoUrl" : "" ,
"emailLogoUrl" : "" ,
"emailFooterMode" : "sent-by" ,
"emailFooterText" : "Grafana Labs" ,
"emailFooterLink" : "https://grafana.com/"
}
}
```
### Status Codes
- **200** – OK
2023-03-15 17:06:31 +00:00
- **401** - Authentication failed, refer to [Authentication API ]({{< relref "/docs/grafana/latest/developers/http_api/auth" >}} ).
2022-09-28 17:03:43 +02:00
- **500** - Unexpected error or server misconfiguration. Refer to server logs for more detail
## Save reports branding settings
`POST /api/reports/settings`
Creates settings if they don't exist, otherwise updates them. These settings are global and used across all the reports.
#### Required permissions
See note in the [introduction ]({{< ref "#reporting-api" >}} ) for an explanation.
| Action | Scope |
| ---------------------- | ----- |
| reports.settings:write | n/a |
### Example request
```http
POST /api/reports/settings HTTP / 1.1
Accept : application/json
Content-Type : application/json
Authorization : Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"branding" : {
"reportLogoUrl" : "https://grafana.com/reportLogo.jpg" ,
"emailLogoUrl" : "https://grafana.com/emailLogo.jpg" ,
"emailFooterMode" : "sent-by" ,
"emailFooterText" : "Grafana Labs" ,
"emailFooterLink" : "https://grafana.com/"
}
}
```
#### JSON Body Schema
| Field name | Data type | Description |
| ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| branding.reportLogoUrl | string | URL of an image used as a logo on every page of the report. |
| branding.emailLogoUrl | string | URL of an image used as a logo in the email. |
| branding.emailFooterMode | string | Can be `sent-by` or `none` .<br/>`sent-by` adds a "Sent by `branding.emailFooterText` " footer link to the email. Requires specifying values in the `branding.emailFooterText` and `branding.emailFooterLink` fields.<br/>`none` suppresses adding a "Sent by" footer link to the email. |
| branding.emailFooterText | string | Text of a URL added to the email "Sent by" footer. |
| branding.emailFooterLink | string | URL address value added to the email "Sent by" footer. |
### Example response
```http
HTTP / 1.1 200 OK
Content-Type : application/json
Content-Length : 35
{
"message" : "Report settings saved"
}
```
### Status Codes
- **200** – OK
- **400** – Bad request (invalid json, missing or invalid fields values, etc.).
2023-03-15 17:06:31 +00:00
- **401** - Authentication failed, refer to [Authentication API ]({{< relref "/docs/grafana/latest/developers/http_api/auth" >}} ).
2022-09-28 17:03:43 +02:00
- **500** - Unexpected error or server misconfiguration. Refer to server logs for more detail
## Send a test email
`POST /api/reports/test-email`
Sends a test email with a report without persisting it in the database.
#### Required permissions
See note in the [introduction ]({{< ref "#reporting-api" >}} ) for an explanation.
| Action | Scope |
| ------------ | ----- |
| reports:send | n/a |
### Example request
See [JSON body schema ]({{< ref "#config-json-body-schema" >}} ) for fields description.
```http
POST /api/reports/test-email HTTP / 1.1
Accept : application/json
Content-Type : application/json
Authorization : Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{ {
"name" : "Report 4" ,
"recipients" : "example-report@grafana.com" ,
"replyTo" : "" ,
"message" : "Hello, please, find the report attached" ,
"schedule" : {
"startDate" : "2022-10-02T10:00:00+02:00" ,
"endDate" : "2022-11-02T20:00:00+02:00" ,
"frequency" : "daily" ,
"intervalFrequency" : "" ,
"intervalAmount" : 0 ,
"workdaysOnly" : true ,
"timeZone" : "Europe/Warsaw"
},
"options" : {
"orientation" : "landscape" ,
"layout" : "grid"
},
"enableDashboardUrl" : true ,
"dashboards" : [
{
"dashboard" : {
"uid" : "7MeksYbmk" ,
},
"timeRange" : {
"from" : "2022-08-08T15:00:00+02:00" ,
"to" : "2022-09-02T17:00:00+02:00"
},
"reportVariables" : {
2024-02-05 20:46:35 +01:00
"variable1" : "Value1"
2022-09-28 17:03:43 +02:00
}
}
],
"formats" : [
"pdf" ,
"csv"
]
}
```
### Example response
```http
HTTP / 1.1 200 OK
Content-Type : application/json
Content-Length : 29
{
"message" : "Test email sent"
}
```
### Status Codes
- **200** – OK
- **400** – Bad request (invalid json, missing or invalid fields values, etc.).
2023-03-15 17:06:31 +00:00
- **401** - Authentication failed, refer to [Authentication API ]({{< relref "/docs/grafana/latest/developers/http_api/auth" >}} ).
2022-09-28 17:03:43 +02:00
- **403** - Forbidden (access denied to a report or a dashboard used in the report).
- **500** - Unexpected error or server misconfiguration. Refer to server logs for more details