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

# List annotations

`GET /api/v2/annotation`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/annotation`
- Auth: API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`

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.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/da68bf029e4c?raw)