annotations

Creates, updates, deletes, gets or lists an annotations resource.

Overview

Name	annotations
Type	Resource
Id	datadog.dashboards.annotations

Fields

The following fields are returned by SELECT queries:

list_annotations

Name	Datatype	Description
id	string (uuid)	Unique identifier of the annotation. (example: 00000000-0000-0000-0000-000000000000)
attributes	object	Attributes of an annotation returned in a response.
type	string	Annotation resource type. (annotation) (example: annotation)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
list_annotations	select	page_id, start_time, end_time	widget_id	Returns a flat list of annotations matching the given page, time window, and optional widget filter.
create_annotation	insert	data		Creates a new annotation on a dashboard or notebook page.<br />Valid color values: gray, blue, purple, green, yellow, red.<br />Valid type values: pointInTime (marks a single moment) or timeRegion (spans a range and requires end_time).
update_annotation	replace	annotation_id, data		Updates an existing annotation.<br />Valid color values: gray, blue, purple, green, yellow, red.<br />Valid type values: pointInTime (marks a single moment) or timeRegion (spans a range and requires end_time).
delete_annotation	delete	annotation_id		Deletes an existing annotation by ID.<br />Returns 204 No Content if the annotation does not exist (idempotent).

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
annotation_id	string (uuid)	The ID of the annotation. (example: 00000000-0000-0000-0000-000000000000)
end_time	integer (int64)	End of the time window in milliseconds since the Unix epoch. (example: 1704153600000)
page_id	string	ID of the page to list annotations for, prefixed with the page type and joined by a colon (for example, dashboard:abc-def-xyz or notebook:1234567890). (example: dashboard:abc-def-xyz)
site	string	The Datadog site (region) for your organization, for example datadoghq.com, us3.datadoghq.com, us5.datadoghq.com, ap1.datadoghq.com, ap2.datadoghq.com, datadoghq.eu, ddog-gov.com. Resolved from the DD_SITE environment variable when set. Optional: defaults to datadoghq.com, or the value of the DD_SITE environment variable when set; a WHERE value overrides both.
start_time	integer (int64)	Start of the time window in milliseconds since the Unix epoch. (example: 1704067200000)
widget_id	string	Optional widget ID to restrict results to annotations on a specific widget.

SELECT examples

list_annotations

Returns a flat list of annotations matching the given page, time window, and optional widget filter.

SELECT
id,
attributes,
type
FROM datadog.dashboards.annotations
WHERE page_id = '{{ page_id }}' -- required
AND start_time = '{{ start_time }}' -- required
AND end_time = '{{ end_time }}' -- required
AND widget_id = '{{ widget_id }}'
;

INSERT examples

create_annotation

Creates a new annotation on a dashboard or notebook page.<br />Valid color values: gray, blue, purple, green, yellow, red.<br />Valid type values: pointInTime (marks a single moment) or timeRegion (spans a range and requires end_time).

INSERT INTO datadog.dashboards.annotations (
data
)
SELECT 
'{{ data }}' /* required */
RETURNING
data
;

Manifest

# Description fields are for documentation purposes
- name: annotations
props:
  - name: data
    description: |
      Data for creating an annotation.
    value:
      attributes:
        color: "{{ color }}"
        description: "{{ description }}"
        end_time: {{ end_time }}
        page_id: "{{ page_id }}"
        start_time: {{ start_time }}
        type: "{{ type }}"
        widget_ids:
          - "{{ widget_ids }}"
      type: "{{ type }}"

REPLACE examples

update_annotation

Updates an existing annotation.<br />Valid color values: gray, blue, purple, green, yellow, red.<br />Valid type values: pointInTime (marks a single moment) or timeRegion (spans a range and requires end_time).

REPLACE datadog.dashboards.annotations
SET 
data = '{{ data }}'
WHERE 
annotation_id = '{{ annotation_id }}' --required
AND data = '{{ data }}' --required
RETURNING
data;

DELETE examples

delete_annotation

Deletes an existing annotation by ID.<br />Returns 204 No Content if the annotation does not exist (idempotent).

DELETE FROM datadog.dashboards.annotations
WHERE annotation_id = '{{ annotation_id }}' --required
;