Chart Annotations API

Endpoint

Chart Annotations API

The Chart Annotations API allows you to programmatically annotate important dates (e.g. feature releases and marketing campaigns) on your organization's charts with a horizontal axis of calendar dates.

Create an Annotation

Authenticate via basic authentication with the credentials API_Key:Secret_Key.

POST https://amplitude.com/api/2/annotations

Below are the required parameters you will need to create an annotation programmatically.

ParameterTypeDescription
app_id (required)integerThe Project ID of the project your chart belongs to.
date (required)dateDate (YYYY-MM-DD) of the annotation.
label (required)stringThe title of your annotation.
chart_id (optional)stringThe ID of the chart (found in URL) you wish to annotate.
details (optional)stringAdditional details you would like to add to the annotation.

IMPORTANT: If you do not include a chart_id, the annotation will be global.

Example Request

curl -d "label=Version 2.4 Release&date=2018-09-16&details=Added new user properties.&chart_id=c4cbl1k" -u API_Key:Secret_Key -X POST https://amplitude.com/api/2/annotations

Example Response

{
        "annotation": 
    {
        "date": "2018-09-16", 
        "details": "Added new user properties.", 
        "id": 50079, 
        "label": "Version 2.4 Release"
        } 
        "success": true
}

Get an Annotation

Authenticate via basic authentication with the credentials API_Key:Secret_Key.

POST https://amplitude.com/api/2/annotation/<id>

Below are the required parameters you will need to get a specific annotation.

ParameterTypeDescription
id (required)integerThe ID of your annotation, which was returned when you created the annotation programmatically.

Example Request

curl -u API_Key:Secret_Key -X GET https://amplitude.com/api/2/annotation/50079

Example Response

{
    "annotation": 
        {
            "date": "2018-09-16", 
            "details": "Added new user properties.", 
            "id": 50079, 
            "label": "Version 2.4 Release"
        }
}

Get All Annotations

Authenticate via basic authentication with the credentials API_Key:Secret_Key. This call will help you fetch all annotations in your project.

Example Request

curl -u API_Key:Secret_Key -X GET https://amplitude.com/api/2/annotations

Example Response

{
    "annotation": 
        {
            "date": "2018-09-16", 
            "details": "Added new user properties.", 
            "id": 50079, 
            "label": "Version 2.4 Release"
        }
}

Did this page help you?