---
title: "List annotations"
method: GET
path: "/api/v2/annotation"
tags: ["Annotations"]
---

# List annotations

`GET /api/v2/annotation`

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

## Query parameters

- `page_id` string, required
- `start_time` integer, required
- `end_time` integer, required
- `widget_id` string

## Response `200`

OK

- AnnotationsResponse — Response containing a list of annotations.
  - `data` AnnotationData[], required — List of annotation resources.
    - `attributes` AnnotationAttributes, required — Attributes of an annotation returned in a response.
      - `author_id` string, required — Identifier of the user who created the annotation.
      - `color` 'gray' | 'blue' | 'purple' | 'green' | 'yellow' | 'red', required — Color used to render the annotation in the UI.
      - `created_at` integer, required — Creation time of the annotation in milliseconds since the Unix epoch.
      - `description` string, required — User-defined text attached to the annotation.
      - `end_time` integer, nullable, required — End time of the annotation in milliseconds since the Unix epoch. Null for `pointInTime` annotations.
      - `modified_at` integer, required — Last modification time of the annotation in milliseconds since the Unix epoch.
      - `page_id` string, required — ID of the page the annotation belongs to, prefixed with the page type and joined by a colon (for example, `dashboard:abc-def-xyz` or `notebook:1234567890`).
      - `start_time` integer, required — Start time of the annotation in milliseconds since the Unix epoch.
      - `type` 'pointInTime' | 'timeRegion', required — Kind of annotation. `pointInTime` annotations mark a single moment in time, while `timeRegion` annotations span a window of time and require an `end_time`.
      - `widget_ids` string[] — IDs of widgets the annotation is associated with. When empty or omitted, the annotation applies to the whole page.
    - `id` string, uuid, required — Unique identifier of the annotation.
    - `type` 'annotation', required — Annotation resource type.

## Other responses

- `400` — Bad Request
- `403` — Forbidden
- `429` — Too many requests
- `500` — Internal Server Error

---

[API](https://skmtc.net/datadog/apis/api-v2.md) · [All operations](https://skmtc.net/datadog/apis/api-v2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/datadog/api-v2/revisions/da68bf029e4c/schema)