2020-07-13 17:09:24 -04:00
---
stage: Monitor
2021-03-18 11:09:04 -04:00
group: Monitor
2020-11-26 01:09:20 -05:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-07-13 17:09:24 -04:00
type: concepts, howto
---
2021-01-28 01:08:59 -05:00
# Dashboard annotations API **(FREE)**
2020-04-21 11:21:10 -04:00
2021-08-30 14:10:36 -04:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29089) in GitLab 12.10 behind a disabled feature flag.
2020-04-21 11:21:10 -04:00
2020-06-02 14:08:32 -04:00
Metrics dashboard annotations allow you to indicate events on your graphs at a single point in time or over a time span.
2020-04-21 11:21:10 -04:00
## Create a new annotation
```plaintext
POST /environments/:id/metrics_dashboard/annotations/
2020-04-22 17:10:00 -04:00
POST /clusters/:id/metrics_dashboard/annotations/
2020-04-21 11:21:10 -04:00
```
Parameters:
| Attribute | Type | Required | Description |
|:---------------|:---------------|:---------|:-----------------------------------------------------------------------------|
2020-10-08 20:08:41 -04:00
| `dashboard_path` | string | yes | ID of the dashboard which needs to be annotated. Treated as a CGI-escaped path, and automatically un-escaped. |
2020-04-21 11:21:10 -04:00
| `starting_at` | string | yes | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` . Timestamp marking start point of annotation. |
2020-11-18 10:09:08 -05:00
| `ending_at` | string | no | Date time string, ISO 8601 formatted, such as `2016-03-11T03:45:40Z` . Timestamp marking end point of annotation. When not supplied, an annotation displays as a single event at the start point. |
2020-04-21 11:21:10 -04:00
| `description` | string | yes | Description of the annotation. |
```shell
2020-05-27 20:08:37 -04:00
curl --header "Private-Token: < your_access_token > " "https://gitlab.example.com/api/v4/environments/1/metrics_dashboard/annotations" \
2020-04-21 11:21:10 -04:00
--data-urlencode "dashboard_path=.gitlab/dashboards/custom_metrics.yml" \
--data-urlencode "starting_at=2016-03-11T03:45:40Z" \
--data-urlencode "description=annotation description"
```
Example Response:
```json
{
"id": 4,
"starting_at": "2016-04-08T03:45:40.000Z",
"ending_at": null,
"dashboard_path": ".gitlab/dashboards/custom_metrics.yml",
"description": "annotation description",
"environment_id": 1,
"cluster_id": null
}
```