2022-05-26 23:06:25 +08:00
---
aliases:
2022-12-10 00:36:04 +08:00
- ../../http_api/annotations/
2023-02-07 01:14:36 +08:00
canonical: /docs/grafana/latest/developers/http_api/annotations/
2022-05-26 23:06:25 +08:00
description: Grafana Annotations HTTP API
keywords:
- grafana
- http
- documentation
- api
- annotation
- annotations
- comment
Explicitly set all front matter labels in the source files (#71548)
* Set every page to have defaults of 'Enterprise' and 'Open source' labels
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Set administration pages to have of 'Cloud', 'Enterprise', and 'Open source' labels
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Set administration/enterprise-licensing pages to have 'Enterprise' labels
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Set administration/organization-management pages to have 'Enterprise' and 'Open source' labels
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Set administration/provisioning pages to have 'Enterprise' and 'Open source' labels
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Set administration/recorded-queries pages to have labels cloud,enterprise
* Set administration/roles-and-permissions/access-control pages to have labels cloud,enterprise
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Set administration/stats-and-license pages to have labels cloud,enterprise
* Set alerting pages to have labels cloud,enterprise,oss
* Set breaking-changes pages to have labels cloud,enterprise,oss
* Set dashboards pages to have labels cloud,enterprise,oss
* Set datasources pages to have labels cloud,enterprise,oss
* Set explore pages to have labels cloud,enterprise,oss
* Set fundamentals pages to have labels cloud,enterprise,oss
* Set introduction/grafana-cloud pages to have labels cloud
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Fix introduction pages products
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Set panels-visualizations pages to have labels cloud,enterprise,oss
* Set release-notes pages to have labels cloud,enterprise,oss
* Set search pages to have labels cloud,enterprise,oss
* Set setup-grafana/configure-security/audit-grafana pages to have labels cloud,enterprise
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Set setup-grafana/configure-security/configure-authentication pages to have labels cloud,enterprise,oss
* Set setup-grafana/configure-security/configure-authentication/enhanced-ldap pages to have labels cloud,enterprise
* Set setup-grafana/configure-security/configure-authentication/saml pages to have labels cloud,enterprise
* Set setup-grafana/configure-security/configure-database-encryption/encrypt-secrets-using-hashicorp-key-vault pages to have labels cloud,enterprise
* Set setup-grafana/configure-security/configure-request-security pages to have labels cloud,enterprise,oss
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Set setup-grafana/configure-security/configure-team-sync pages to have labels cloud,enterprise
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Set setup-grafana/configure-security/export-logs pages to have labels cloud,enterprise
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
* Set troubleshooting pages to have labels cloud,enterprise,oss
* Set whatsnew pages to have labels cloud,enterprise,oss
* Apply updated labels from review
Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com>
Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com>
---------
Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com>
Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com>
2023-07-18 16:10:12 +08:00
labels:
products:
- enterprise
- oss
2022-12-10 00:36:04 +08:00
title: Annotations HTTP API
2022-05-26 23:06:25 +08:00
---
2017-10-07 16:31:39 +08:00
2022-04-04 20:53:58 +08:00
# Annotations API
2017-10-07 16:31:39 +08:00
2022-11-21 18:07:59 +08:00
Annotations are saved in the Grafana database (sqlite, mysql or postgres). Annotations can be organization annotations that can be shown on any dashboard by configuring an annotation data source - they are filtered by tags. Or they can be tied to a panel on a dashboard and are then only shown on that panel.
2022-04-04 20:53:58 +08:00
2025-03-06 20:59:08 +08:00
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
2017-10-07 16:31:39 +08:00
## Find Annotations
`GET /api/annotations?from=1506676478816&to=1507281278816&tags=tag1&tags=tag2&limit=100`
2022-05-21 03:48:52 +08:00
**Required permissions**
2022-04-04 20:53:58 +08:00
2025-03-06 20:59:08 +08:00
See note in the [introduction ](#annotations-api ) for an explanation.
2022-04-04 20:53:58 +08:00
2024-09-10 16:50:03 +08:00
<!-- prettier - ignore - start -->
| Action | Scope |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `annotations:read` | < ul >< li > `annotations:*`</ li >< li > `annotations:type:*`</ li >< li > `dashboards:*`</ li >< li > `dashboards:uid:*`</ li >< li > `folders:*`</ li >< li > `folders:uid:*`</ li ></ ul > |
{ .no-spacing-list }
<!-- prettier - ignore - end -->
2022-04-04 20:53:58 +08:00
2017-10-07 16:31:39 +08:00
**Example Request**:
```http
GET /api/annotations?from=1506676478816& to=1507281278816& tags=tag1& tags=tag2& limit=100 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
```
Query Parameters:
- `from` : epoch datetime in milliseconds. Optional.
- `to` : epoch datetime in milliseconds. Optional.
2018-04-13 16:58:29 +08:00
- `limit` : number. Optional - default is 100. Max limit for results returned.
2017-10-07 16:31:39 +08:00
- `alertId` : number. Optional. Find annotations for a specified alert.
2025-06-14 02:59:24 +08:00
- `dashboardId` : Deprecated. Use dashboardUID instead.
2022-07-27 09:52:34 +08:00
- `dashboardUID` : string. Optional. Find annotations that are scoped to a specific dashboard, when dashboardUID presents, dashboardId would be ignored.
2017-10-07 16:31:39 +08:00
- `panelId` : number. Optional. Find annotations that are scoped to a specific panel
2018-03-22 22:52:09 +08:00
- `userId` : number. Optional. Find annotations created by a specific user
- `type` : string. Optional. `alert` |`annotation` Return alerts or user created annotations
2022-04-04 20:53:58 +08:00
- `tags` : string. Optional. Use this to filter organization annotations. Organization annotations are annotations from an annotation data source that are not connected specifically to a dashboard or panel. To do an "AND" filtering with multiple tags, specify the tags parameter multiple times e.g. `tags=tag1&tags=tag2` .
2017-10-07 16:31:39 +08:00
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
[
{
"id": 1124,
"alertId": 0,
2022-05-02 17:35:36 +08:00
"dashboardUID": "uGlb_lG7z",
2017-10-07 16:31:39 +08:00
"panelId": 2,
"userId": 1,
"userName": "",
"newState": "",
"prevState": "",
"time": 1507266395000,
2019-08-16 16:49:30 +08:00
"timeEnd": 1507266395000,
2017-10-07 16:31:39 +08:00
"text": "test",
"tags": [
"tag1",
"tag2"
],
"data": {}
},
{
"id": 1123,
"alertId": 0,
2022-05-02 17:35:36 +08:00
"dashboardUID": "jcIIG-07z",
2017-10-07 16:31:39 +08:00
"panelId": 2,
"userId": 1,
"userName": "",
"newState": "",
"prevState": "",
"time": 1507265111000,
"text": "test",
"tags": [
"tag1",
"tag2"
],
"data": {}
}
]
```
2019-08-16 17:45:30 +08:00
> Starting in Grafana v6.4 regions annotations are now returned in one entity that now includes the timeEnd property.
2017-10-07 16:31:39 +08:00
## Create Annotation
2025-06-14 02:59:24 +08:00
Creates an annotation in the Grafana database. The `dashboardUid` and `panelId` fields are optional.
2022-04-04 20:53:58 +08:00
If they are not specified then an organization annotation is created and can be queried in any dashboard that adds
2021-08-06 21:52:36 +08:00
the Grafana annotations data source. When creating a region annotation include the timeEnd property.
2021-02-17 21:51:27 +08:00
2021-08-06 21:52:36 +08:00
The format for `time` and `timeEnd` should be epoch numbers in millisecond resolution.
2017-10-07 16:31:39 +08:00
`POST /api/annotations`
2022-05-21 03:48:52 +08:00
**Required permissions**
2022-04-04 20:53:58 +08:00
2025-03-06 20:59:08 +08:00
See note in the [introduction ](#annotations-api ) for an explanation.
2022-04-04 20:53:58 +08:00
2024-09-10 16:50:03 +08:00
<!-- prettier - ignore - start -->
| Action | Scope |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `annotations:create` | < ul >< li > `annotations:*`</ li >< li > `annotations:type:*`</ li >< li > `dashboards:*`</ li >< li > `dashboards:uid:*`</ li >< li > `folders:*`</ li >< li > `folders:uid:*`</ li ></ ul > |
{ .no-spacing-list }
<!-- prettier - ignore - end -->
2022-04-04 20:53:58 +08:00
2022-08-03 16:01:25 +08:00
**Required JSON Body Fields**
- `text` : description of the annotation.
2017-10-07 16:31:39 +08:00
**Example Request**:
2019-02-06 21:26:43 +08:00
```http
2017-10-07 16:31:39 +08:00
POST /api/annotations HTTP/1.1
Accept: application/json
Content-Type: application/json
{
2022-05-02 17:35:36 +08:00
"dashboardUID":"jcIIG-07z",
2017-10-07 16:31:39 +08:00
"time":1507037197339,
"timeEnd":1507180805056,
"tags":["tag1","tag2"],
"text":"Annotation Description"
}
```
**Example Response**:
2019-02-06 21:26:43 +08:00
```http
2017-10-07 16:31:39 +08:00
HTTP/1.1 200
Content-Type: application/json
2017-11-16 21:24:56 +08:00
{
"message":"Annotation added",
"id": 1,
}
2017-10-07 16:31:39 +08:00
```
2019-08-16 17:45:30 +08:00
> The response for this HTTP request is slightly different in versions prior to v6.4. In prior versions you would
2021-08-06 21:52:36 +08:00
> also get an endId if you where creating a region. But in 6.4 regions are represented using a single event with time and
> timeEnd properties.
2019-08-16 17:45:30 +08:00
2017-10-18 16:13:02 +08:00
## Create Annotation in Graphite format
Creates an annotation by using Graphite-compatible event format. The `when` and `data` fields are optional. If `when` is not specified then the current time will be used as annotation's timestamp. The `tags` field can also be in prior to Graphite `0.10.0`
format (string with multiple tags being separated by a space).
`POST /api/annotations/graphite`
2022-05-21 03:48:52 +08:00
**Required permissions**
2022-04-04 20:53:58 +08:00
2025-03-06 20:59:08 +08:00
See note in the [introduction ](#annotations-api ) for an explanation.
2022-04-04 20:53:58 +08:00
2024-09-10 16:50:03 +08:00
| Action | Scope |
| -------------------- | ------------------------------- |
| `annotations:create` | `annotations:type:organization` |
2022-04-04 20:53:58 +08:00
2017-10-18 16:13:02 +08:00
**Example Request**:
2019-02-06 21:26:43 +08:00
```http
2017-10-18 16:13:02 +08:00
POST /api/annotations/graphite HTTP/1.1
Accept: application/json
Content-Type: application/json
{
"what": "Event - deploy",
"tags": ["deploy", "production"],
"when": 1467844481,
2024-02-29 23:08:45 +08:00
"data": "deploy of main branch happened at Wed Jul 6 22:34:41 UTC 2016"
2017-10-18 16:13:02 +08:00
}
```
**Example Response**:
2019-02-06 21:26:43 +08:00
```http
2017-10-18 16:13:02 +08:00
HTTP/1.1 200
Content-Type: application/json
2017-11-16 21:24:56 +08:00
{
"message":"Graphite annotation added",
"id": 1
}
2017-10-18 16:13:02 +08:00
```
2019-02-06 21:26:43 +08:00
## Update Annotation
2017-10-07 16:31:39 +08:00
`PUT /api/annotations/:id`
2019-02-06 21:26:43 +08:00
Updates all properties of an annotation that matches the specified id. To only update certain property, consider using the [Patch Annotation ](#patch-annotation ) operation.
2019-01-27 19:49:22 +08:00
2022-05-21 03:48:52 +08:00
**Required permissions**
2022-04-04 20:53:58 +08:00
2025-03-06 20:59:08 +08:00
See note in the [introduction ](#annotations-api ) for an explanation.
2022-04-04 20:53:58 +08:00
2024-09-10 16:50:03 +08:00
<!-- prettier - ignore - start -->
| Action | Scope |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `annotations:write` | < ul >< li > `annotations:*`</ li >< li > `annotations:type:*`</ li >< li > `dashboards:*`</ li >< li > `dashboards:uid:*`</ li >< li > `folders:*`</ li >< li > `folders:uid:*`</ li ></ ul > |
{ .no-spacing-list }
<!-- prettier - ignore - end -->
2022-04-04 20:53:58 +08:00
2017-10-07 16:31:39 +08:00
**Example Request**:
2019-02-06 21:26:43 +08:00
```http
2017-10-07 16:31:39 +08:00
PUT /api/annotations/1141 HTTP/1.1
Accept: application/json
2019-01-27 19:49:22 +08:00
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
2017-10-07 16:31:39 +08:00
Content-Type: application/json
{
"time":1507037197339,
"timeEnd":1507180805056,
"text":"Annotation Description",
"tags":["tag3","tag4","tag5"]
}
```
2019-02-06 21:26:43 +08:00
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
{
"message":"Annotation updated"
}
```
## Patch Annotation
2021-08-06 21:52:36 +08:00
2019-01-27 19:49:22 +08:00
`PATCH /api/annotations/:id`
Updates one or more properties of an annotation that matches the specified id.
2019-08-16 17:45:30 +08:00
This operation currently supports updating of the `text` , `tags` , `time` and `timeEnd` properties.
2019-02-06 04:41:39 +08:00
2022-05-21 03:48:52 +08:00
**Required permissions**
2022-04-04 20:53:58 +08:00
2025-03-06 20:59:08 +08:00
See note in the [introduction ](#annotations-api ) for an explanation.
2022-04-04 20:53:58 +08:00
2024-09-10 16:50:03 +08:00
<!-- prettier - ignore - start -->
| Action | Scope |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `annotations:write` | < ul >< li > `annotations:*`</ li >< li > `annotations:type:*`</ li >< li > `dashboards:*`</ li >< li > `dashboards:uid:*`</ li >< li > `folders:*`</ li >< li > `folders:uid:*`</ li ></ ul > |
{ .no-spacing-list }
<!-- prettier - ignore - end -->
2022-04-04 20:53:58 +08:00
2019-01-27 19:49:22 +08:00
**Example Request**:
2019-02-06 21:26:43 +08:00
```http
2019-01-27 19:49:22 +08:00
PATCH /api/annotations/1145 HTTP/1.1
Accept: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
Content-Type: application/json
{
"text":"New Annotation Description",
"tags":["tag6","tag7","tag8"]
}
```
2019-02-06 21:26:43 +08:00
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
{
"message":"Annotation patched"
}
```
2017-10-07 16:31:39 +08:00
## Delete Annotation By Id
2018-04-10 03:09:37 +08:00
`DELETE /api/annotations/:id`
2017-10-07 16:31:39 +08:00
Deletes the annotation that matches the specified id.
2022-05-21 03:48:52 +08:00
**Required permissions**
2022-04-04 20:53:58 +08:00
2025-03-06 20:59:08 +08:00
See note in the [introduction ](#annotations-api ) for an explanation.
2022-04-04 20:53:58 +08:00
2024-09-10 16:50:03 +08:00
<!-- prettier - ignore - start -->
| Action | Scope |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `annotations:delete` | < ul >< li > `annotations:*`</ li >< li > `annotations:type:*`</ li >< li > `dashboards:*`</ li >< li > `dashboards:uid:*`</ li >< li > `folders:*`</ li >< li > `folders:uid:*`</ li ></ ul > |
{ .no-spacing-list }
<!-- prettier - ignore - end -->
2022-04-04 20:53:58 +08:00
2017-10-07 16:31:39 +08:00
**Example Request**:
```http
2018-04-10 03:09:37 +08:00
DELETE /api/annotations/1 HTTP/1.1
2017-10-07 16:31:39 +08:00
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
2019-02-06 21:26:43 +08:00
{
"message":"Annotation deleted"
}
2019-08-16 17:45:30 +08:00
```
2021-07-21 16:23:15 +08:00
## Find Annotations Tags
`GET /api/annotations/tags`
Find all the event tags created in the annotations.
2022-05-21 03:48:52 +08:00
**Required permissions**
2022-04-04 20:53:58 +08:00
2025-03-06 20:59:08 +08:00
See note in the [introduction ](#annotations-api ) for an explanation.
2022-04-04 20:53:58 +08:00
2024-09-10 16:50:03 +08:00
| Action | Scope |
| ------------------ | ----- |
| `annotations:read` | N/A |
2022-04-04 20:53:58 +08:00
2021-07-21 16:23:15 +08:00
**Example Request**:
```http
GET /api/annotations/tags?tag=out HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
```
Query Parameters:
- `tag` : Optional. A string that you can use to filter tags.
- `limit` : Optional. A number, where the default is 100. Max limit for results returned.
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
{
"result": {
"tags": [
{
"tag": "outage",
"count": 1
}
]
}
}
```