Chart Annotations API

地域

ベースURLは、プロジェクトのデータのレジデンシーによって異なります。このページ内のすべての例では、プロジェクトがAmplitudeのEUデータセンターを利用している場合を除き、デフォルトのベースURLを使用してください。EUデータセンターを利用している場合は、この表に記載されているEU用のベースURLを使用してください。

リクエストはhttps://amplitude.com（デフォルト）またはhttps://analytics.eu.amplitude.com（EU）に送信されます。https://analytics.amplitude.comのホスト名はアナリティクスウェブアプリ（ブラウザーUI）です。RESTリクエストにはanalytics.amplitude.comではなく、この表に記載されているホストを使用してください。

データのレジデンシー	ベースURL
デフォルト	`https://amplitude.com`
欧州連合	`https://analytics.eu.amplitude.com`

注釈カテゴリ

注釈カテゴリを管理して注釈を整理します。カテゴリを作成し、その名前を更新し、それらを注釈に割り当てます。

注釈カテゴリを作成する

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"
}'

ボディパラメータ

パラメータ	概要
`category`	必須です。文字列です。カテゴリの名前です。

レスポンス

json

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

エラーレスポンス

400 - 無効なフィールド
409 - カテゴリはすでに存在します

すべての注釈カテゴリを取得する

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

クエリパラメータ

パラメータ	概要
`category`	オプションです。文字列です。指定した場合、指定されたカテゴリのみを返します。それ以外の場合は、すべてのカテゴリが返されます。

レスポンス

json

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

エラーレスポンス

400 - 無効なカテゴリ
404 - カテゴリが見つかりません

IDで注釈カテゴリを取得する

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

パスパラメータ

パラメータ	概要
`category_id`	必須です。整数です。カテゴリのID。

レスポンス

json

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

エラーレスポンス

400 - 無効なカテゴリID
404 - カテゴリが見つかりません

注釈カテゴリを更新する

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"
}'

パスパラメータ

パラメータ	概要
`category_id`	必須です。整数です。更新するカテゴリのID。

ボディパラメータ

パラメータ	概要
`category`	必須です。文字列です。カテゴリの新しい名前です。

レスポンス

json

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

エラーレスポンス

400 - 無効なカテゴリID
404 - カテゴリが見つかりません
409 - カテゴリはすでに存在します

注釈カテゴリを削除する

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

パスパラメータ

パラメータ	概要
`category_id`	必須です。整数です。削除するカテゴリのID。

レスポンス

json

{
  "success": true
}

エラーレスポンス

400 - 無効なカテゴリID
404 - カテゴリが見つかりません

注釈カテゴリを一括更新する

カテゴリを複数の注釈に一度に割り当てることができます。

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]
}'

パスパラメータ

パラメータ	概要
`category_id`	必須です。整数です。割り当てるカテゴリのID。

ボディパラメータ

パラメータ	概要
`annotation_ids`	必須です。配列。更新する注釈IDのリスト。

レスポンス

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
        },
        …
    ]
}

エラーレスポンス

400 - 無効なカテゴリID
400 - 無効な注釈ID
400 - 1つ以上の無効な注釈ID
404 - カテゴリが見つかりません

注釈

チャート注釈を作成、取得、更新、削除します。注釈は、単一の日付だけでなく、時間単位の細かい精度で期間を指定することもできます。

注釈を作成する

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"
}'

ボディパラメータ

パラメータ	概要
`label`	必須です。文字列です。注釈のタイトルです。
`start`	必須です。文字列です。この注釈の開始に対応するタイムスタンプ（ISO 8601形式：`YYYY-MM-DDThh:mmTZD`）。例：`"2025-11-01T07:00:00+00:00"`。
`category`	オプションです。文字列です。注釈が属するカテゴリの名前です。
`chart_id`	オプションです。文字列です。注釈を付けるチャートのID（URL内にあります）。`chart_id`を含めない場合、注釈はグローバルになり、プロジェクトのすべてのチャートに表示されます。
`details`	オプションです。文字列です。注釈の詳細です。
`end`	オプションです。文字列です。この注釈の終わりに対応するタイムスタンプ（ISO 8601形式：`YYYY-MM-DDThh:mmTZD`）。例：`"2025-11-10T07:00:00+01:00"`。

レスポンス

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
  }
}

エラーレスポンス

400 - 無効なフィールド
404 - カテゴリが見つかりません

すべての注釈を取得する

プロジェクト内のすべてのチャート注釈を取得します。カテゴリ、チャート、日付範囲によるフィルタリングをサポートしています。

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}'

クエリパラメータ

パラメータ	概要
`category`	オプションです。文字列です。指定した場合、このカテゴリ内の注釈のみが返されます。 `chart_id`フィルターと結合することはありません。
`chart_id`	オプションです。文字列です。指定した場合、このチャートに表示されている注釈のみが返されます。`category`フィルターと結合することはありません。
`start`	オプションです。文字列です。指定した場合、`start`以降に発生した注釈のみをISO 8601形式（`YYYY-MM-DDThh:mmTZD`）で返します。例：`"2025-11-10T07:00:00+01:00"`。
`end`	オプションです。文字列です。指定した場合、`end`以前に発生した注釈のみをISO 8601形式（`YYYY-MM-DDThh:mmTZD`）で返します。注釈が特定の日付範囲にまたがる場合、注釈の終了日は`end`入力日より前である必要があります。例：`"2025-11-10T07:00:00+01:00"`。

レスポンス

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
    }
  ]
}

エラーレスポンス

400 - 無効なリクエスト
409 - 競合しています

単一の注釈を取得する

IDで単一チャートの注釈を取得します。

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

パスパラメータ

パラメータ	概要
`annotation_id`	必須です。整数です。取得する注釈のID。

レスポンス

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
  }
}

エラーレスポンス

400 - 無効な注釈のID
404 - 注釈が見つかりません

注釈を更新する

特定の注釈を更新します。部分的な更新をサポートします。リクエスト本文で指定したフィールドのみが更新されます。

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"
}'

パスパラメータ

パラメータ	概要
`annotation_id`	必須です。整数です。更新する注釈のID。

ボディパラメータ

パラメータ	概要
`label`	オプションです。文字列です。注釈のタイトルです。
`start`	オプションです。文字列です。この注釈の開始に対応するタイムスタンプ（ISO 8601形式：`YYYY-MM-DDThh:mmTZD`）。例：`"2025-11-01T07:00:00+00:00"`。
`category`	オプションです。文字列です。注釈が属するカテゴリの名前です。
`chart_id`	オプションです。文字列です。注釈を付けるチャートのID（URL内にあります）。`chart_id`を含めない場合、注釈はグローバルになり、プロジェクトのすべてのチャートに表示されます。特定のチャートとの関連付けを削除し、注釈をグローバルに表示できるようにするには、`null`に設定します。
`details`	オプションです。文字列です。注釈の詳細です。
`end`	オプションです。文字列です。この注釈の終わりに対応するタイムスタンプ（ISO 8601形式：`YYYY-MM-DDThh:mmTZD`）。例：`"2025-11-10T07:00:00+01:00"`。終了時間を削除するには、`null`に設定します。

レスポンス

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
  }
}

エラーレスポンス

400 - 無効なフィールド
404 - 注釈が見つかりません
404 - カテゴリが見つかりません

注釈を削除する

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

パスパラメータ

パラメータ	概要
`annotation_id`	必須です。整数です。削除する注釈のID。

レスポンス

json

{
  "success": true
}

エラーレスポンス

400 - 無効な注釈のID
404 - 注釈が見つかりません

これは役に立ちましたか？