Chart Annotations API

The Chart Annotations API lets you programmatically annotate important dates like feature releases and marketing campaigns on your organization's charts with a horizontal axis of calendar dates.

Authentication

API uses basic authentication, using the API key and secret key for your project. Pass base64-encoded credentials in the request header like {api-key}:{secret-key}. api-key replaces username, and secret-key replaces the password.

Your authorization header should look something like this:

--header 'Authorization: Basic YWhhbWwsdG9uQGFwaWdlZS5jb206bClwYXNzdzByZAo'`

For more information, see Find your API Credentials

Endpoints

Region	Endpoint
Standard server	`https://amplitude.com/api/2/annotations`
EU residency server	`https://analytics.eu.amplitude.com/api/2/annotations`

Create an annotation

1POST /api/2/annotations?app_id=yourAppID&date=YYYY-MM-DD&label=yourLabel&chart_id=yourChartID&details=yourDetails HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded

Query parameters

Parameter	Description
`app_id`	Required. Integer. The Project ID of the project your chart belongs to.
`date`	Required. Date. Date (YYYY-MM-DD) of the annotation.
`label`	Required. String. The title of your annotation.
`chart_id`	Optional. String. The ID of the chart (found in URL) to annotate. If you don't include a `chart_id`, the annotation is global and appears on all charts in the project.
`details`	Optional. String. Details for the annotation.

Response

 1{
 2        "annotation":
 3    {
 4        "date": "2023-09-16",
 5        "details": "Added new user properties.",
 6        "id": 50079,
 7        "label": "Version 2.4 Release"
 8        }
 9        "success": true
10}

Get all chart annotations

Retrieves all chart annotations in your project.

1GET /api/2/annotations HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded

Response

 1{
 2    "data": [
 3        {
 4            "id": 160419,
 5            "date": "2021-09-01",
 6            "label": "First September",
 7            "details": "My annotation"
 8        },
 9        {
10            "id": 160427,
11            "date": "2021-09-01",
12            "label": "Annotation 2",
13            "details": "Another annotation"
14        },
15        {
16            "id": 160507,
17            "date": "2021-09-25",
18            "label": "Annotation 3",
19            "details": "Chart annotation"
20        },
21        {
22            "id": 160508,
23            "date": "2021-09-30",
24            "label": "Annotation 4",
25            "details": "Made another annotation"
26        }
27    ]
28}

Get a single chart annotation

Retrieve a single chart annotation, by ID.

1GET /api/2/annotations?id=CHARTID HTTP/1.1
2Host: amplitude.com
3Authorization: Basic {api-key}:{secret-key} #credentials must be base64 encoded

Query parameters

Name	Description
`id`	Required. Annotation ID.

Response

A successful response returns the chart annotation's data.

 1{
 2    "data": [
 3 
 4        {
 5            "id": 160427,
 6            "date": "2022-01-31",
 7            "label": "Chart Annotation 1",
 8            "details": "This is a chart annotation"
 9        }
10    ]
11}