This API allows you to interact programmatically with the [Reporting]({{< relref "../../dashboards/create-reports/" >}}) feature.
> The Reporting API is not stabilized yet, it is still in active development and may change without prior notice.
> Reporting is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../../enterprise/" >}}).
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "../../administration/roles-and-permissions/access-control/custom-role-actions-scopes/" >}}) for more information.
## Send a report
## List all reports
`GET /api/reports`
#### Required permissions
See note in the [introduction]({{< ref "#reporting-api" >}}) for an explanation.
- **500** – Unexpected error or server misconfiguration. Refer to server logs for more details.
## Get a report
`GET /api/reports/:id`
#### Required permissions
See note in the [introduction]({{< ref "#reporting-api" >}}) for an explanation.
> This API endpoint is experimental and may be deprecated in a future release. On deprecation, a migration strategy will be provided and the endpoint will remain functional until the next major release of Grafana.
| 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. |
| 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.
| 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. |
| 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. |
| 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.).
Tania
3 years ago
committed by