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

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

POST /api/2/annotations?app_id=yourAppID&date=YYYY-MM-DD&label=yourLabel&chart_id=yourChartID&details=yourDetails HTTP/1.1
Host: amplitude.com
Authorization: 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

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

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

Get all chart annotations

Retrieves all chart annotations in your project.

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

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

Response

{
    "data": [
        {
            "id": 160419,
            "date": "2021-09-01",
            "label": "First September",
            "details": "My annotation"
        },
        {
            "id": 160427,
            "date": "2021-09-01",
            "label": "Annotation 2",
            "details": "Another annotation"
        },
        {
            "id": 160507,
            "date": "2021-09-25",
            "label": "Annotation 3",
            "details": "Chart annotation"
        },
        {
            "id": 160508,
            "date": "2021-09-30",
            "label": "Annotation 4",
            "details": "Made another annotation"
        }
    ]
}

{
    "data": [
        {
            "id": 160419,
            "date": "2021-09-01",
            "label": "First September",
            "details": "My annotation"
        },
        {
            "id": 160427,
            "date": "2021-09-01",
            "label": "Annotation 2",
            "details": "Another annotation"
        },
        {
            "id": 160507,
            "date": "2021-09-25",
            "label": "Annotation 3",
            "details": "Chart annotation"
        },
        {
            "id": 160508,
            "date": "2021-09-30",
            "label": "Annotation 4",
            "details": "Made another annotation"
        }
    ]
}

Get a single chart annotation

Retrieve a single chart annotation, by ID.

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

GET /api/2/annotations?id=CHARTID HTTP/1.1
Host: amplitude.com
Authorization: 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.

{
    "data": [
 
        {
            "id": 160427,
            "date": "2022-01-31",
            "label": "Chart Annotation 1",
            "details": "This is a chart annotation"
        }
    ]
}

{
    "data": [
    
            {
        &quot;id&quot;: 160427,
        &quot;date&quot;: &quot;2022-01-31&quot;,
        &quot;label&quot;: &quot;Chart Annotation 1&quot;,
        &quot;details&quot;: &quot;This is a chart annotation&quot;
    }
]

    {
        &quot;id&quot;: 160427,
        &quot;date&quot;: &quot;2022-01-31&quot;,
        &quot;label&quot;: &quot;Chart Annotation 1&quot;,
        &quot;details&quot;: &quot;This is a chart annotation&quot;
    }
]
    
}