Create X Activity Subscription

Creates a subscription for an X activity event. OAuth2 user-context tokens must hold the scope matching the requested event_type: dm.read for chat.* and dm.* events, like.read for like.* events, mute.read for mute.* events, block.read for block.* events, follows.read for subscriptions.* events, and tweet.read for all other event types. Mute and block subscriptions are actor-only: filter.user_id must identify the authenticated user and direction is not supported. subscriptions.* events require a user-context token and filter.user_id must identify the authenticated user. Optional filter.qualifiers further narrow supported chat, follow, unfollow, like, and subscriptions events.

POST /2/activity/subscriptions

Create X Activity Subscription

cURL

curl --request POST \
  --url https://api.x.com/2/activity/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filter": {
    "keyword": "<string>",
    "qualifiers": {},
    "user_id": "<string>"
  },
  "expires_at": "<string>",
  "tag": "<string>",
  "webhook_id": "<string>"
}
'

200

{
  "data": {
    "subscription": {
      "created_at": "<string>",
      "event_type": "<string>",
      "expires_at": "<string>",
      "filter": {
        "direction": "<string>",
        "keyword": "<string>",
        "qualifiers": {},
        "user_id": "<string>"
      },
      "subscription_id": "<string>",
      "tag": "<string>",
      "updated_at": "<string>",
      "webhook_id": "<string>"
    }
  },
  "errors": [
    {
      "detail": "<string>",
      "resource_type": "<string>",
      "title": "<string>",
      "type": "https://api.x.com/2/problems/resource-not-found",
      "parameter": "<string>",
      "resource_id": "<string>",
      "status": 123,
      "value": "<string>"
    }
  ]
}

Authorizations

OAuth2UserTokenUserTokenBearerToken

Authorization · string · header · required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

event_type · enum<string> · required

Activity event type in dot notation. chat.conversation_join is a deprecated alias of chat.conversation.join; responses always use the canonical name.

Available options: profile.update.bio, profile.update.profile_picture, profile.update.banner_picture, profile.update.screenname, profile.update.geo, profile.update.url, profile.update.verified_badge, profile.update.affiliate_badge, profile.update.handle, news.new, follow.follow, follow.unfollow, subscriptions.subscribe, subscriptions.unsubscribe, spaces.start, spaces.end, broadcast.start, broadcast.end, broadcast.chat, broadcast.chat.remove, chat.received, chat.sent, chat.conversation.join, chat.conversation_join, chat.conversation.member_added, chat.conversation.member_removed, chat.conversation.admin_added, chat.conversation.admin_removed, chat.update.group_name, chat.update.restrictions, dm.sent, dm.received, dm.indicate_typing, dm.read, post.create, post.delete, post.mention.create, post.reply.create, post.quote.create, post.repost.create, like.create, mute.mute, mute.unmute, block.block, block.unblock

filter · object · required

Subscription filter.

Show child attributes

expires_at · string

Optional RFC 3339 expiration time. Re-creating the same subscription refreshes this value; omitting it makes the subscription permanent.

tag · string

Optional caller-defined tag.

Required string length: 1 - 200

webhook_id · string

Webhook to deliver the subscription events to.

Pattern: ^[0-9]{1,19}$

Response

200

application/json

The request has succeeded.

data · object

Show child attributes

errors · object[]

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

Option 8

Option 9

Option 10

Option 11

Option 12

Option 13

Option 14

Option 15

Option 16

Option 17

Option 18

Option 19

Option 20

Option 21

Option 22

Option 23

Option 24

Option 25

Option 26

Option 27

Option 28

Option 29

Option 30

Option 31

Option 32

Option 33

Option 34

Option 35

Option 36

Option 37

Option 38

Option 39

Option 40

Option 41

Option 42

Option 43

Option 44

Option 45

Option 46

Option 47

Option 48

Option 49

Option 50

Option 51

Option 52

Option 53

Option 54

Option 55

Option 56

Option 57

Option 58

Option 59

Option 60

Option 61

Show child attributes