メインコンテンツへスキップ
このガイドでは、X Activity API のエンドポイントを使用してイベントを購読・受信する方法を説明します。通常は次の3つの手順を行います。
  1. フィルタリング対象のユーザーについて、そのユーザーの User ID を特定する
  2. そのユーザーに対し、フィルタリングしたいイベント種別のサブスクリプションを作成する
  3. Webhook または永続的な HTTP ストリーム接続でイベントを受信する

​
ユーザーIDの取得

サブスクリプションを作成する前に、フィルター対象のアカウントのユーザーIDを把握しておく必要があります。ここでは例として、XDevelopers のハンドルを使用します。ユーザーIDは次のいくつかの方法で確認できます: ユーザー名からユーザーIDを取得する: 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" "https://api.x.com/2/users/by/username/xdevelopers"
自分のユーザーidを取得する： 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" https://api.x.com/2/users/me
両エンドポイントは、サブスクリプションフィルターで使用できる id フィールドを含むユーザー情報を返します。以下に JSON レスポンスの例を示します。 
{
    "data": {
        "id": "2244994945",
        "name": "Developers",
        "username": "XDevelopers"
    }
}

​
サブスクリプションの作成

次のステップはサブスクリプションの作成です。この例では、XDevelopers の自己紹介（bio）更新にサブスクライブします。そのために、JSON のボディで user_id と event_type を指定します。この場合、event_type は ProfileBioUpdate です。 X Developers のユーザー ID 2244994945 と、任意のタグを渡します。 
{
  "event_type": "ProfileBioUpdate",
  "filter": {
    "user_id": "2244994945"
  },
  "tag": "Xdevelopersの自己紹介の更新"
}
XAA に関連するすべてのエンドポイントの認可には、開発者ポータルで取得したベアラー・トークンを使用します。 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  https://api.x.com/2/activity/subscriptions \
  -X POST \
  -d '{
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "2244994945"
    },
    "tag": "Xdevelopersの自己紹介更新"
  }'
リクエストが正常に処理されると、サブスクリプションが作成されます。 
{
  "data":[
    {
      "created_at":"2025-10-09T16:35:08.000Z",
      "event_type":"ProfileBioUpdate",
      "filter":{
        "user_id":"2244994945"
      },
      "subscription_id":"1976325569252868096",
      "tag": "Xdevelopersの自己紹介更新",
      "updated_at":"2025-10-09T16:35:08.000Z"
    }
  ],
  "meta": {
    "total_subscriptions": 1
  }
}

​
イベントの取得

サブスクリプションを作成すると、webhooks もしくは永続的な HTTP ストリーム経由でイベントを受信できます。この例では、永続的な HTTP ストリームを開きます。 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" https://api.x.com/2/activity/stream
Xdevelopers アカウントがプロフィールの自己紹介を更新すると、そのイベントはストリームで配信されます。 
{
  "data": {
    "filter": {
      "user_id": "2244994945"
    },
    "event_type": "ProfileBioUpdate",
    "tag": "Xdevelopersの自己紹介の更新",
    "payload": {
      "before": "火星と車",
      "after": "火星、車、AI"
    }
  }
}

​
サブスクリプション管理

X Activity API は、標準的な CRUD 操作でサブスクリプションを管理できるエンドポイントを提供します。

​
サブスクリプションの作成

イベントを受け取るための新しいサブスクリプションを作成します： 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X POST \
  https://api.x.com/2/activity/subscriptions \
  -d '{
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "123456789"
    },
    "tag": "my bio updates",
    "webhook_id": "1976325569252868099"
  }'
注記:
  • tag フィールドは任意です。配信時のイベント識別に役立ちます。
  • webhook_id フィールドも任意です。Webhook の設定方法はwebhook ドキュメントをご覧ください。webhook_id が指定されている場合、ストリームが開いているときはストリームへの配信に加えて、指定された Webhook にもイベントが配信されます。
レスポンス: 
{
  "data": {
    "subscription_id": "1976325569252868096",
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "123456789"
    },
    "created_at": "2025-10-09T16:35:08.000Z",
    "updated_at": "2025-10-09T16:35:08.000Z",
    "tag": "my bio updates",
    "webhook_id": "1976325569252868099"
  }
}

​
サブスクリプションの一覧

アプリケーションで有効なサブスクリプションをすべて取得します。 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  https://api.x.com/2/activity/subscriptions
レスポンス 
{
  "data": [
    {
      "subscription_id": "1976325569252868096",
      "event_type": "ProfileBioUpdate",
      "filter": {
        "user_id": "123456789"
      },
      "created_at": "2025-10-09T16:35:08.000Z",
      "updated_at": "2025-10-10T03:50:59.000Z",
    },
    {
      "subscription_id": "1976325569252868097",
      "event_type": "ProfilePictureUpdate",
      "filter": {
        "user_id": "987654321"
      },
      "created_at": "2025-10-08T14:35:08.000Z",
      "updated_at": "2025-10-08T14:35:08.000Z",
    }
  ],
  "meta": {
    "total_subscriptions": 2
  }
}

​
サブスクリプションの削除

サブスクリプションを削除するには: 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X DELETE \
  https://api.x.com/2/activity/subscriptions/1976325569252868096
レスポンス 
{
  "data": {
    "deleted": true
  },
  "meta": {
    "total_subscriptions": 0
  }
}
total_subscriptions は、削除操作後にアプリに関連付けられている残りのサブスクリプション数を示します。

​
サブスクリプションの更新

PUT エンドポイントを使用すると、サブスクリプションの配信方法またはタグを更新できます。 filter や event_type を更新する場合は、既存のサブスクリプションを削除して新規に作成する必要があります。 
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X PUT \
  https://api.x.com/2/activity/subscriptions/1976325569252868096 \
  -d '{
    "tag": "my new tag",
    "webhook_id": "192846273860294839"
  }'
応答: 
{
  "data": {
    "subscription_id": "1976325569252868096",
    "event_type": "ProfileBioUpdate",
    "filter": {
      "user_id": "123456789"
    },
    "created_at": "2025-10-09T16:35:08.000Z",
    "updated_at": "2025-10-10T17:10:58.000Z",
    "tag": "my new tag",
    "webhook_id": "192846273860294839"
  },
  "meta": {
    "total_subscriptions": 1
  }
}