このページでは

行動コホート 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

制限と考慮事項

  • グロースプランとエンタープライズプランの場合、Behavioral Cohorts Download APIには1か月あたり500件のリクエスト制限があります。各Get one cohortリクエストは、この制限にカウントされます。 Get usage エンドポイントを使用して、現在の使用状況を確認してください。
  • Amplitudeは最大200万ユーザーのコホートサイズをサポートしています。 より大規模なコホートについては、次のいずれかを使用してください。
  • 同時実行数の制限は、コホートダウンロードとDashboard REST API全体で5件のリクエストです。
  • コホートダウンロードは非同期APIを使用しています。 コホートを取得するには、次の3つのステップを完了してください。
    1. 単一のコホートを要求してください。
    2. コホートのステータスをポーリングします。
    3. ファイルをダウンロードします。
  • コホート ダウンロードでは、単一コホートのリクエストを1アプリあたり10分間で60件、また1アプリあたり1分間で4件の並列リクエストに制限します。
  • Amplitudeは、単一のリクエストを100,000個のIDに制限します。

すべてのコホートの取得

あるアプリの検出可能なすべてのコホートを取得します。 単一のコホートを取得するには、応答で返された各コホートに対して idを使用します。

curl --location --request GET 'https://amplitude.com/api/3/cohorts' \
-u '{api_key}:{secret_key}'

クエリパラメータ

名前概要
includeSyncInfoオプションです。ブール値trueに設定すると、レスポンスにコホート同期メタデータが含まれます。この応答には、ワンタイム同期と無効化された同期は含まれません。

レスポンス

レスポンスは次のスキーマを持つJSONオブジェクトです。

json
{
    "cohorts": [
        { COHORT_OBJECT },
        ...
        { COHORT_OBJECT },
    ]
}

返される各COHORT_OBJECTには次のスキーマがあります。

json
{
    "appId": integer,
    "archived": boolean, // whether cohort is archived
    "definition": { COHORT_DEFINITION }, // Amplitude internal representation of Cohort Definition
    "description": string,
    "finished": boolean, // Amplitude internal use to decide whether a training cohort has finished ML training
    "id": string,
    "name": string,
    "owners": string[],
    "viewers": string[],
    "published": boolean, // whether cohort is discoverable by other users
    "size": integer,
    "type": string, // Amplitude internal representation on different cohort types
    "lastMod": timestamp, // last modified date
    "createdAt": timestamp,
    "lastComputed": timestamp,
    "hidden": boolean, // Amplitude internal use case to hide a cohort
    "metadata": string[], // cohort created from funnel/microscope might have this
    "view_count": integer,
    "popularity": integer, // cohort created from chart might have this
    "last_viewed": timestamp,
    "chart_id": string, // cohort created from chart will have this
    "edit_id": string, // cohort created from chart will have this
    "is_predictive": boolean,
    "is_official_content": boolean,
    "location_id": string, // cohort created from chart might have this
    "shortcut_ids": string[],
    "syncMetadata": COHORT_SYNC_METADATA[]
}

各COHORT_SYNC_METADATAには次のスキーマがあります。

json
{
    "target": string,
    "frequency": string, // support minute (real-time), hourly, daily
    "last_successful": timestamp,
    "last_failure": timestamp,
    "params": { COHORT_SYNC_LEVEL_PARAM }
}

以下はサンプル結果です。

json
"cohorts": [{
    "appId": 123456,
    "archived": false,
    "definition": {
        "version": 3,
        "countGroup": {
            "name": "User",
            "is_computed": false
        },
        "cohortType": "UNIQUES",
        "andClauses": [{
            "negated": false,
            "orClauses": [{
                "type": "event",
                "time_type": "rolling",
                "time_value": 30,
                "offset": 0,
                "interval": 1,
                "type_value": "_active",
                "operator": ">=",
                "operator_value": 1,
                "group_by": [],
                "metric": null
            }]
        }],
        "referenceFrameTimeParams": {}
    },
    "description": "test description",
    "finished": true,
    "id": "id_12345",
    "name": "Test Cohort 1",
    "owners": [
        "demo@amplitude.com"
    ],
    "viewers": [],
    "published": true,
    "size": 111,
    "type": "redshift",
    "lastMod": 1679437294,
    "createdAt": 1679437288,
    "lastComputed": 1679440233,
    "hidden": false,
    "metadata": null,
    "view_count": null,
    "popularity": null,
    "last_viewed": null,
    "chart_id": null,
    "edit_id": null,
    "is_predictive": false,
    "is_official_content": false,
    "location_id": null,
    "shortcut_ids": [],
    "syncMetadata": [{
        "target": "braze",
        "frequency": "hourly",
        "last_successful": "2023-03-21T16:09:58.848454-07:00",
        "last_failure": null,
        "params": {
            "user_id": "demo@amplitude.com"
        }
    }]
}],

1つのコホートを取得する

その cohort_id を使用して、検出可能なコホートを取得します。これは、コホートダウンロード操作の最初のステップです。 レスポンスで返されたrequest_idを使用して、エクスポートステータスをポーリングします。

curl --location --request GET 'https://amplitude.com/api/5/cohorts/request/id'
-u '{api_key}:{secret_key}'

パスパラメータ

名前概要
id必須です。 コホート ID。

クエリパラメータ

名前概要
propsオプションです。整数です。 1に設定すると、レスポンスオブジェクトにユーザープロパティが含まれます。 リクエストがタイムアウトし続ける場合は、0に設定するか、設定を解除します。
propKeysオプションです。 string[] 応答に含める1つ以上のユーザープロパティ。 必要な数のpropKeysパラメータを追加します。 未定義で、かつ props=1 の場合、レスポンスオブジェクトは利用可能なすべてのユーザープロパティを返します。

レスポンス

単一のコホートリクエストは、次のJSONオブジェクトを含む202レスポンスコードを返します。

json
{
  "request_id": "<request_id>",
  "cohort_id": "<cohort_id>"
}

認証または cohort_idが無効な場合、リクエストはエラーを返します。

リクエストのステータスを取得する

コホートについて取得したrequest_idを使用して、リクエストステータスをポーリングします。 これはコホートダウンロード操作のステップ2です。

curl --location --request GET 'https://amplitude.com/api/5/cohorts/request-status/:request_id' \
-u '{api_key}:{secret_key}''

パスパラメータ

名前概要
request_id必須です。 get one cohortリクエストで取得されたリクエスト ID。

レスポンス

ジョブがまだ実行中の場合、リクエストステータスは 202 コードと async_status JOB INPROGRESS を返します。

json
{
  "request_id": "<request_id>",
  "cohort_id": "<cohort_id>",
  "async_status": "JOB INPROGRESS"
}

ジョブの実行が完了した場合、リクエストステータスは 200 コードと async_status JOB COMPLETED を返します。

json
{
  "request_id": "<request_id>",
  "cohort_id": "<cohort_id>",
  "async_status": "JOB COMPLETED"
}

コホートをダウンロードする

ジョブの実行が完了したら、コホートをダウンロードします。 以下は基本的なリクエストです。

curl --location --request GET 'https://amplitude.com/api/5/cohorts/request/:requestId/file' \
-u '{api_key}:{secret_key}'

パスパラメータ

名前概要
request_id必須です。 get one cohortリクエストで取得されたリクエスト ID。
  • 小規模なコホートの場合、応答本文にはコホートデータが含まれています。
  • 大規模なコホートの場合は、データをダウンロードする必要があります。 このレスポンスは302レスポンスコードとともに、事前に署名されたAmazon S3ダウンロードURLにリダイレクトされます。ダウンロードURLは1分間有効ですので、すぐにアクセスしてください。
  • APIリクエストのリンク (https://amplitude.com/api/5/cohorts/request/:requestId/file) は、7日間有効です。この7日間のうちに、同じリクエストを送信して新しいS3ダウンロードリンクを取得できます。各S3リンクは1分間有効です。
  • ほとんどのAPIクライアントは、S3リンクからデータを自動的にダウンロードします。APIクライアントが自動的にコホートをダウンロードしない場合、手動でアクセスできる時間は1分です。

使用状況を確認する

行動コホートダウンロードAPIの現在の月間使用状況と制限を確認してください。

curl --location --request GET 'https://amplitude.com/api/3/cohorts/usage' \
-u '{api_key}:{secret_key}'

レスポンス

json
{
  "rest_download": {
    "limit": 500,
    "usage": 42,
    "resets_at": "2026-06-01T00:00:00"
  }
}

使用状況は毎月1日（UTC）にリセットされます。

コホートをアップロードする

ユーザーIDまたはAmplitude IDのセットをアップロードすることで、新しいコホートを作成するか、既存のコホートを更新します。 以下は、プレースホルダ値を使用した基本的なリクエストの例です。

curl --location --request POST 'https://amplitude.com/api/3/cohorts/upload' \
--header 'Content-Type: application/json' \
-u '{api_key}:{secret_key}''
--data-raw '{
    "name": "Cohort Name",
    "app_id": amplitude_project,
    "id_type": "BY_AMP_ID",
    "cg": "group_id",
    "ids": [
            "amplitude_id",
            "amplitude_id"
    ],
    "owner": "cohort_owner",
    "published": true
}'

ボディパラメータ

パラメータ概要
name必須です。 文字列です。 コホートの名前です。
app_id必須です。 整数です。 コホートを含むAmplitudeプロジェクトの識別子。
id_type必須です。 文字列です。 idsフィールドに送信されるIDの種類。 有効なオプションは BY_AMP_ID または BY_USER_ID です。
cgオプションです。文字列です。 既存のグループの名前を入力して、それに基づいてコホートを作成します。
ids必須です。 文字列[]。 コホートに含める1つ以上のユーザーIDまたはAmplitude ID。 id_typeフィールドにIDタイプを指定します。
owner必須です。 文字列です。 Amplitudeでのコホートの所有者のログインメールアドレス。
published必須です。 ブール値そのコホートが発見可能か隠されているか否か。
skip_saveオプションです。ブール値保存せずにアップロードを検証する場合は、true に設定してください。デフォルトは false です。
skip_invalid_idsオプションです。ブール値無効な ID をスキップし、残りの有効な ID をアップロードするには、true に設定します。 リクエストに無効なIDが含まれている場合にアップロードを終了するには、falseに設定します。デフォルトは true です。
existing_cohort_idオプションです。文字列です。 既存のコホートの ID。 リクエストでアップロードされた ID は、指定されたコホートのコンテンツに代わります。 たとえば、1a2bc3dはあなたのコホートのIDです。これは、コホートのURLに含まれています：https://analytics.amplitude.com/accountname/cohort/1a2bc3d。

レスポンス

レスポンスは次のスキーマを持つJSONオブジェクトです。

json
{
  "cohortId": "COHORT_ID",
  "metadata": {
    "matched": 1234,
    "totals": 1232,
    "invalid_ids_sample": ["INVALID_ID1", "INVALID_ID2"]
  }
}

応答エラー

パラメータタイプ概要
エラーエラーJSONエラーの詳細。

コホートエラーレスポンスJSONをアップロード

パラメータ概要
http_code整数です。 HTTPエラーが表示される場合、そのエラーを提供します。
type文字列です。 エラーの種類について説明します。
message文字列です。 エラーについて説明します。
metadataJSONオブジェクト。エラーの原因についてより詳細に説明します。 たとえば、どのユーザーID値が無効であるかなどです。

コホートメンバーシップの更新

IDを追加および削除して、既存のコホートメンバーシップを段階的に更新します。

curl --location --request POST 'https://amplitude.com/api/3/cohorts/membership' \
--header 'Content-Type: application/json' \
-u '{api_key}:{secret_key}' \
--data-raw '{
    "cohort_id": "COHORT_ID",
    "memberships": [
        {
            "ids": [
                "ID",
                "ID"
            ],
            "id_type": "BY_ID",
            "operation": "ADD"
        },
        {
            "ids": [
                "ID",
                "ID"
            ],
            "id_type": "BY_ID",
            "operation": "REMOVE"
        },
        {
            "ids": [
                "name",
                "name"
            ],
            "id_type": "BY_NAME",
            "operation": "ADD"
        }
    ],
    "skip_invalid_ids": true
}

リクエスト本文

パラメータ概要
cohort_id必須です。 文字列です。 既存のコホートの ID。 リクエストでアップロードされたIDは、指定されたコホートのメンバーシップを更新します。
count_groupオプションです。文字列です。 指定されたIDのカウントグループ。カウントグループは、コホートの既存のカウントグループと一致している必要があります。count_groupのデフォルトはUserです。
memberships必須です。 メンバーシップJSONのリスト。追加または削除する ID を識別する JSON オブジェクトの配列です。
skip_invalid_idsオプションです。ブール値リクエストに無効な ID が含まれている場合に、コホート メンバーシップを更新せずにリクエストを終了するには、false に設定します。無効な ID をスキップし、残りの有効な ID を適用するには、true に設定します。 デフォルトは true です。

メンバーシップリクエストJSON

パラメータ概要
ids必須です。 文字列[]。 追加または削除する ID のリスト。
id_type必須です。 文字列です。 idsフィールドで送信された ID の種類。 有効なオプションは BY_ID と BY_NAME です。User カウントグループの場合、BY_ID はAmplitude IDであり、BY_NAME はユーザーIDです。その他のカウント グループの場合、BY_ID はグループ ID であり、BY_NAME はグループ名です。
operation必須です。 文字列です。 idsフィールドに適用する操作です。 有効なオプションは次のとおりです：ADDおよびREMOVE

レスポンス

パラメータ概要
cohort_id文字列です。 メンバーシップ情報が更新された既存のコホートの ID。
memberships_resultmemberships_resultJSON のリスト。 メンバーシップ更新操作の結果を識別する JSON オブジェクトの配列です。

メンバーシップ応答 JSON

パラメータ概要
skipped_ids文字列のリスト。メンバーシップ操作エントリ内のスキップされたIDのリスト。
id_type文字列です。 このメンバーシップ操作エントリ内のidsフィールドに対して送信されるIDの種類。
operation文字列です。 このメンバーシップ操作エントリ内のidsフィールドに適用された操作

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