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

This 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}
Was this page helpful?

Thanks for your feedback!

May 21st, 2024

Need help? Contact Support

Visit Amplitude.com

Have a look at the Amplitude Blog

Learn more at Amplitude Academy

© 2024 Amplitude, Inc. All rights reserved. Amplitude is a registered trademark of Amplitude, Inc.