On this page

Chart Annotations API

Regions

The base URL depends on your project's data residency. In all examples on this page, use the default base URL unless your project uses Amplitude's EU data center—in that case use the EU base URL in this table.

Requests go to https://amplitude.com (default) or https://analytics.eu.amplitude.com (EU). The https://analytics.amplitude.com hostname is the Analytics web app (browser UI); use the hosts in this table for REST requests, not analytics.amplitude.com.

Data residencyBase URL
Defaulthttps://amplitude.com
EUhttps://analytics.eu.amplitude.com

Annotation categories

Manage annotation categories to organize your annotations. Create categories, update their names, and assign them to annotations.

Create an annotation category

bash
curl --location --request POST 'https://amplitude.com/api/3/annotation-categories' \
--header 'Authorization: Basic {api-key}:{secret-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "category": "Releases"
}'

Body parameters

ParameterDescription
categoryRequired. String. The name of the category.

Response

json
{
  "data": {
    "id": 6789,
    "name": "Releases"
  }
}

Error responses

  • 400 - Invalid field
  • 409 - Category already exists

Get all annotation categories

bash
curl --location --request GET 'https://amplitude.com/api/3/annotation-categories' \
-u '{api-key}:{secret-key}'

Query parameters

ParameterDescription
categoryOptional. String. If specified, returns only the specified category. Otherwise, returns all categories.

Response

json
{
  "data": [
    {
      "id": 12345,
      "name": "Alerts"
    },
    {
      "id": 6789,
      "name": "Releases"
    }
  ]
}

Error responses

  • 400 - Invalid category
  • 404 - Category not found

Get an annotation category by ID

bash
curl --location --request GET 'https://amplitude.com/api/3/annotation-categories/:category_id' \
-u '{api-key}:{secret-key}'

Path parameters

ParameterDescription
category_idRequired. Integer. The ID of the category.

Response

json
{
  "data": {
    "id": 12345,
    "name": "Alerts"
  }
}

Error responses

  • 400 - Invalid category ID
  • 404 - Category not found

Update an annotation category

bash
curl --location --request PUT 'https://amplitude.com/api/3/annotation-categories/:category_id' \
--header 'Authorization: Basic {api-key}:{secret-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "category": "Updated Category Name"
}'

Path parameters

ParameterDescription
category_idRequired. Integer. The ID of the category to update.

Body parameters

ParameterDescription
categoryRequired. String. The new name of the category.

Response

json
{
  "data": {
    "id": 569,
    "category": "Updated category name"
  }
}

Error responses

  • 400 - Invalid category ID
  • 404 - Category not found
  • 409 - Category already exists

Delete an annotation category

bash
curl --location --request DELETE 'https://amplitude.com/api/3/annotation-categories/:category_id' \
-u '{api-key}:{secret-key}'

Path parameters

ParameterDescription
category_idRequired. Integer. The ID of the category to delete.

Response

json
{
  "success": true
}

Error responses

  • 400 - Invalid category ID
  • 404 - Category not found

Bulk update annotation categories

Assign a category to multiple annotations at once.

bash
curl --location --request PUT 'https://amplitude.com/api/3/annotation-categories/bulk/:category_id' \
--header 'Authorization: Basic {api-key}:{secret-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "annotation_ids": [12345, 67890, 11111]
}'

Path parameters

ParameterDescription
category_idRequired. Integer. The ID of the category to assign.

Body parameters

ParameterDescription
annotation_idsRequired. Array. A list of annotation IDs to update.

Response

json
{
    "data": [
        {
            "id": 12345,
            "start": "2025-12-18T15:00:00+00:00",
            "label": "test",
            "details": null,
            "category": {
                "id": 12345,
                "category": "Alerts"
            },
            "end": null,
            "chart_id": null
        },
        …
    ]
}

Error responses

  • 400 - Invalid category ID
  • 400 - Invalid annotation IDs
  • 400 - One or more invalid annotation ID
  • 404 - Category not found

Annotations

Create, retrieve, update, and delete chart annotations. Annotations can span single dates or time ranges with hourly granularity.

Create an annotation

bash
curl --location --request POST 'https://amplitude.com/api/3/annotations' \
--header 'Authorization: Basic {api-key}:{secret-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "label": "Feature X Release",
  "start": "2025-11-01T07:00:00+00:00",
  "category": "Releases",
  "chart_id": "abc123",
  "details": "This marks the release of feature X",
  "end": "2025-11-10T07:00:00+01:00"
}'

Body parameters

ParameterDescription
labelRequired. String. The title of your annotation.
startRequired. String. Timestamp corresponding to the start of this annotation in ISO 8601 format (YYYY-MM-DDThh:mmTZD). For example: "2025-11-01T07:00:00+00:00".
categoryOptional. String. The name of the category that the annotation belongs to.
chart_idOptional. String. The ID of the chart (found in the URL) to annotate. If you don't include chart_id, the annotation is global and appears on all charts for your project.
detailsOptional. String. Details for the annotation.
endOptional. String. Timestamp corresponding to the end of this annotation in ISO 8601 format (YYYY-MM-DDThh:mmTZD). For example: "2025-11-10T07:00:00+01:00".

Response

json
{
  "data": {
    "id": 12345,
    "start": "2025-11-01T07:00:00+00:00",
    "details": "This marks the release of feature X",
    "category": {
      "id": 45678,
      "name": "Releases"
    },
    "end": "2025-11-10T07:00:00+01:00",
    "label": "Feature X Release",
    "chart_id": null
  }
}

Error responses

  • 400 - Invalid field
  • 404 - Category not found

Get all annotations

Retrieves all chart annotations in your project. Supports filtering by category, chart, and date range.

bash
curl --location --request GET 'https://amplitude.com/api/3/annotations?category=Releases&start=2025-11-01T07:00:00+00:00&end=2025-11-30T07:00:00+00:00' \
-u '{api-key}:{secret-key}'

Query parameters

ParameterDescription
categoryOptional. String. If specified, only returns annotations in this category. Doesn't combine with chart_id filter.
chart_idOptional. String. If specified, only returns annotations that show on this chart. Doesn't combine with category filter.
startOptional. String. If specified, only returns annotations that occur after start in ISO 8601 format (YYYY-MM-DDThh:mmTZD). For example: "2025-11-10T07:00:00+01:00".
endOptional. String. If specified, only returns annotations that occur before end in ISO 8601 format (YYYY-MM-DDThh:mmTZD). If the annotation spans a date range, the annotation's end date must be before end input. For example: "2025-11-10T07:00:00+01:00".

Response

json
{
  "data": [
    {
      "id": 12345,
      "start": "2025-11-01T07:00:00+00:00",
      "details": "This marks the release of feature X",
      "category": {
        "id": 45678,
        "name": "Releases"
      },
      "end": "2025-11-10T07:00:00+01:00",
      "label": "Feature X Release",
      "chart_id": null
    }
  ]
}

Error responses

  • 400 - Invalid request
  • 409 - Conflict

Get a single annotation

Retrieves a single chart annotation by ID.

bash
curl --location --request GET 'https://amplitude.com/api/3/annotations/:annotation_id' \
-u '{api-key}:{secret-key}'

Path parameters

ParameterDescription
annotation_idRequired. Integer. The ID of the annotation to retrieve.

Response

json
{
  "data": {
    "id": 12345,
    "start": "2025-11-01T07:00:00+00:00",
    "details": "This marks the release of feature X",
    "category": {
      "id": 45678,
      "name": "Releases"
    },
    "end": "2025-11-10T07:00:00+01:00",
    "label": "Feature X Release",
    "chart_id": null
  }
}

Error responses

  • 400 - Invalid annotation ID
  • 404 - Annotation not found

Update an annotation

Updates a specific annotation. Supports partial updates. Only the fields you specify in the request body are updated.

bash
curl --location --request PUT 'https://amplitude.com/api/3/annotations/:annotation_id' \
--header 'Authorization: Basic {api-key}:{secret-key}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "label": "Updated Feature X Release",
  "end": "2025-11-15T07:00:00+01:00"
}'

Path parameters

ParameterDescription
annotation_idRequired. Integer. The ID of the annotation to update.

Body parameters

ParameterDescription
labelOptional. String. The title of your annotation.
startOptional. String. Timestamp corresponding to the start of this annotation in ISO 8601 format (YYYY-MM-DDThh:mmTZD). For example: "2025-11-01T07:00:00+00:00".
categoryOptional. String. The name of the category that the annotation belongs to.
chart_idOptional. String. The ID of the chart (found in the URL) to annotate. If you don't include chart_id, the annotation is global and appears on all charts for your project. Set to null to remove the association to a specific chart and make the annotation visible globally.
detailsOptional. String. Details for the annotation.
endOptional. String. Timestamp corresponding to the end of this annotation in ISO 8601 format (YYYY-MM-DDThh:mmTZD). For example: "2025-11-10T07:00:00+01:00". Set to null to remove the end time.

Response

json
{
  "data": {
    "id": 12345,
    "start": "2025-11-01T07:00:00+00:00",
    "details": "This marks the release of feature X",
    "category": {
      "id": 45678,
      "name": "Releases"
    },
    "end": "2025-11-15T07:00:00+01:00",
    "label": "Updated Feature X Release",
    "chart_id": null
  }
}

Error responses

  • 400 - Invalid field
  • 404 - Annotation not found
  • 404 - Category not found

Delete an annotation

bash
curl --location --request DELETE 'https://amplitude.com/api/3/annotations/:annotation_id' \
-u '{api-key}:{secret-key}'

Path parameters

ParameterDescription
annotation_idRequired. Integer. The ID of the annotation to delete.

Response

json
{
  "success": true
}

Error responses

  • 400 - Invalid annotation ID
  • 404 - Annotation not found

Was this helpful?