> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.

# イベントストリーミングのための X Activity API クイックスタートガイド

> このガイドでは、X Activity API エンドポイントを使用してイベントをサブスクライブし受信する方法を説明します。X API v2 standard tier の activity に関するリファレンスです。

export const Button = ({href, children}) => {
  return <div className="not-prose">
    <a href={href}>
      <button className="x-btn">
        <span>{children}</span>
        <svg width="3" height="24" viewBox="0 -9 3 24" class="h-6 rotate-0 overflow-visible"><path d="M0 0L3 3L0 6" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"></path></svg>
      </button>
    </a>
  </div>;
};

このガイドでは、X Activity API エンドポイントを使用してイベントをサブスクライブし受信する方法を説明します。一般的に 3 つのステップがあります:

1. イベントをフィルタリングしたいユーザーの User ID を特定する
2. そのユーザーに対してフィルタリングしたいイベントタイプのサブスクリプションを作成する
3. Webhook または永続的な HTTP ストリーム接続を使ってイベントを受信する

<Note>
  **前提条件**

  始める前に、次のものが必要です:

  * 承認済みアプリを持つ[開発者アカウント](https://developer.x.com/en/portal/petition/essential/basic-info)
  * アプリの [Bearer Token](/resources/fundamentals/authentication)
</Note>

***

## ユーザー ID の取得

サブスクリプションを作成する前に、フィルタリングしたいアカウントのユーザー ID を知る必要があります。この例では、XDevelopers ハンドルを使用します。ユーザー ID は、以下を含むいくつかの方法でルックアップできます:

**ユーザー名でユーザー ID をルックアップ:**

```bash theme={null}
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" "https://api.x.com/2/users/by/username/xdevelopers"
```

**自分自身のユーザー ID を取得:**

```bash theme={null}
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" https://api.x.com/2/users/me
```

どちらのエンドポイントも、サブスクリプションフィルターで使用できる `id` フィールドを含むユーザー情報を返します。JSON レスポンスの例は以下のとおりです:

```json theme={null}
{
    "data": {
        "id": "2244994945",
        "name": "Developers",
        "username": "XDevelopers"
    }
}
```

***

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

次のステップはサブスクリプションを作成することです。この例では、XDevelopers の bio 更新をサブスクライブします。そのためには、`user_id` と `event_type` を JSON ボディで渡します。この場合、`event_type` は `profile.update.bio` です。

X Developer のユーザー ID: `2244994945` と、オプションのタグを渡します:

```json theme={null}
{
  "event_type": "profile.update.bio",
  "filter": {
    "user_id": "2244994945"
  },
  "tag": "Xdevelopers' bio updates"
}
```

認可には (developer portal からの) [bearer token](https://docs.x.com/fundamentals/authentication/oauth-2-0/overview#bearer-token-also-known-as-app-only) を使用します。app-only bearer token は、このような公開イベントに対して機能します。一部のイベントは非公開で、代わりに [user-context (OAuth 2.0)](https://docs.x.com/fundamentals/authentication/oauth-2-0/overview#oauth-2-0-authorization-code-flow-with-pkce) 認証が必要です — 詳しくは[イベントのプライバシーと認証](/x-api/activity/introduction#event-privacy-and-authentication)を参照してください。

```bash theme={null}
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  https://api.x.com/2/activity/subscriptions \
  -X POST \
  -d '{
    "event_type": "profile.update.bio",
    "filter": {
      "user_id": "2244994945"
    },
    "tag": "Xdevelopers' bio updates"
  }'
```

リクエストが成功すると、サブスクリプションが作成されます:

```json title="profile.update.bio" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data":[
    {
      "created_at":"2025-10-09T16:35:08.000Z",
      "event_type":"profile.update.bio",
      "filter":{
        "user_id":"2244994945"
      },
      "subscription_id":"1976325569252868096",
      "tag": "Xdevelopers' bio updates",
      "updated_at":"2025-10-09T16:35:08.000Z"
    }
  ],
  "meta": {
    "total_subscriptions": 1
  }
}
```

***

## イベントの取得

サブスクリプションを作成したら、[Webhook](https://docs.x.com/x-api/webhooks/introduction) または永続的な HTTP ストリーム経由でイベントを受信できます。この例では、永続的な HTTP ストリームを開きます:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" https://api.x.com/2/activity/stream
```

Xdevelopers アカウントがプロフィール bio を更新すると、イベントがストリーム経由で配信されます:

```json title="profile.update.bio" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "filter": {
      "user_id": "2244994945"
    },
    "event_type": "profile.update.bio",
    "tag": "Xdevelopers' bio updates",
    "payload": {
      "before": "Mars & Cars",
      "after": "Mars, Cars & AI"
    }
  }
}
```

***

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

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

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

イベントを受信するための新しいサブスクリプションを作成します:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X POST \
  https://api.x.com/2/activity/subscriptions \
  -d '{
    "event_type": "profile.update.bio",
    "filter": {
      "user_id": "123456789"
    },
    "tag": "my bio updates",
    "webhook_id": "1976325569252868099"
  }'
```

<Note>
  * `tag` フィールドはオプションです。配信時にイベントを識別するのに役立ちます。
  * `webhook_id` フィールドもオプションです。Webhook をセットアップする方法は [webhook ドキュメント](https://docs.x.com/x-api/webhooks/introduction)を参照してください。`webhook_id` が指定されている場合、イベントは提供された Webhook に配信され、ストリームが開いている場合はストリームにも配信されます。
</Note>

**レスポンス:**

```json title="profile.update.bio" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "subscription_id": "1976325569252868096",
    "event_type": "profile.update.bio",
    "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"
  }
}
```

### サブスクリプションの一覧表示

アプリケーションのすべてのアクティブなサブスクリプションを取得します:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  https://api.x.com/2/activity/subscriptions
```

**レスポンス:**

```json title="profile.update.bio" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": [
    {
      "subscription_id": "1976325569252868096",
      "event_type": "profile.update.bio",
      "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": "profile.update.profile_picture",
      "filter": {
        "user_id": "987654321"
      },
      "created_at": "2025-10-08T14:35:08.000Z",
      "updated_at": "2025-10-08T14:35:08.000Z"
    }
  ],
  "meta": {
    "total_subscriptions": 2
  }
}
```

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

サブスクリプションを削除します:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X DELETE \
  https://api.x.com/2/activity/subscriptions/1976325569252868096
```

**レスポンス:**

```json theme={null}
{
  "data": {
    "deleted": true
  },
  "meta": {
    "total_subscriptions": 0
  }
}
```

`total_subscriptions` は、削除操作後にアプリに関連付けられている残りのサブスクリプション数を示します。

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

PUT エンドポイントを使用すると、サブスクリプションの配信方法やタグを更新できます。

`filter` または `event_type` の更新には、既存のサブスクリプションを削除して新しいものを追加する必要があります。

```bash theme={null}
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"
  }'
```

**レスポンス:**

```json title="profile.update.bio" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "data": {
    "subscription_id": "1976325569252868096",
    "event_type": "profile.update.bio",
    "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
  }
}
```

***

## 次のステップ

<CardGroup cols={2}>
  <Card title="イベントペイロード" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" href="/x-api/activity/event-payloads" width="24" height="24" data-path="icons/xds/icon-brackets.svg">
    各アクティビティイベントタイプのサンプル JSON
  </Card>

  <Card title="API リファレンス" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/activity/activity-stream" width="24" height="24" data-path="icons/xds/icon-code.svg">
    完全なエンドポイントドキュメント
  </Card>

  <Card title="Webhooks" icon="webhook" href="/x-api/webhooks/introduction">
    Webhook 配信をセットアップ
  </Card>
</CardGroup>