Enterprise
The Account Activity API provides you the ability to subscribe to realtime activities related to a user account via webhooks. This means that you can receive realtime Posts, Direct Messages, and other account events from one or more of your owned or subscribed accounts through a single connection.
You will receive all related activities below for each user subscription on your webhook registration:
Activity types | |
---|---|
* Posts (by user) * Post deletes (by user) * @mentions (of user) * Replies (to or from user) * Retweets (by user or of user) * Quote Tweets (by user or of user) * Retweets of Quoted Tweets (by user or of user) * Likes (by user or of user) * Follows (by user or of user) * Unfollows (by user) | * Blocks (by user) * Unblocks (by user) * Mutes (by user) * Unmutes (by user) * Direct Messages sent (by user) * Direct Messages received (by user) * Typing indicators (to user) * Read receipts (to user) * Subscription revokes (by user) |
Tier | Pricing | Number of unique subscriptions | Number of webhooks | Reliability and Activity Recovery |
---|---|---|---|---|
Enterprise | Contact sales | Up to 500+ | 3+ | Retries and Replay |
<URL>
e.g. https://yourdomain.com/webhooks/twitter/
<CONSUMER_KEY>
e.g. xvz1evFS4wEEPTGEFPHBog
<ACCESS_TOKEN>
e.g. 370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb
<:WEBHOOK_ID>
e.g. 1234567890
<CONSUMER_KEY>
e.g. xvz1evFS4wEEPTGEFPHBog
<SUBSCRIBING_USER'S_ACCESS_TOKEN>
e.g. 370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb
favorite_events
via a POST request to your webhook URL for each Favorite your subscribers receive.crc_token
parameter. When that request is received, your web app needs to build an encrypted response_token
based on the crc_token
parameter and your app’s Consumer Secret (details below). The response_token must be encoded in JSON (see example below) and returned within three seconds. When successful, a webhook id
will be returned.
A CRC will be sent when you register your webhook URL, so implementing your CRC response code is a fundamental first step. Once your webhook is established, X will trigger a CRC roughly every 24 hours from the last time we received a successful response. Your app can also trigger a CRC when needed by making a PUT request with your webhook id
. Triggering a CRC is useful as you develop your webhook application, after deploying new code and restarting your service.
The crc_token
should be expected to change for each incoming CRC request and should be used as the message in the calculation, where your Consumer Secret is the key.
In the event that the response is not posted within 3 seconds or becomes invalid, events will cease to be sent to the registered webhook.
crc_token
and your app Consumer SecretECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES128-SHA256:AES128-SHA:AES256-GCM-SHA384:AES256-SHA256:AES256-SHA:ECDHE-RSA-DES-CBC3-SHA:DES-CBC3-SHA
Method | Enterprise |
Registers a webhook URL / Generates a webhook_id | POST webhooks |
Returns all webhook URLs and their statuses | GET webhooks |
Delete app’s current webhook configuration | DELETE webhooks/:webhook_id |
Manually trigger a CRC request | PUT webhooks/:webhook_id |
Method | Enterprise |
Add new user subscription | POST webhooks/:webhook_id/subscriptions/all |
Retrieve a user subscription | GET webhooks/:webhook_id/subscriptions/all |
Returns a list of all active subscriptions | GET webhooks/:webhook_id/subscriptions/all/list |
Deactivates a user subscription using application only OAuth | DELETE webhooks/:webhook_id/subscriptions/:user_id/all.json |
Description | **Endpoint ** | OAuth 1.0a (user context) | OAuth 2.0 Bearer Token (application-only) |
Register a new webhook URL for the given application context | POST account_activity/webhooks | ✓ | |
Return all URLs and their statuses for the given application | GET account_activity/webhooks | ✓ | |
Trigger a challenge response check (CRC) for a given webhook’s URL | PUT account_activity/webhooks/:webhook_id | ✓ | |
Subscribe the application to a user’s account events | POST account_activity/webhooks/:webhook_id/subscriptions/all | ✓ * | |
Return a count of currently active subscriptions | GET account_activity/subscriptions/count | ✓ | |
Check if a webhook configuration is subscribed to a user’s events | GET account_activity/webhooks/:webhook_id/subscriptions/all | ✓ * | |
Return a list of currently active subscriptions | GET account_activity/webhooks/:webhook_id/subscriptions/all/list | ✓ | |
Delete a webhook | DELETE account_activity/webhooks/:webhook_id | ✓ | |
[DEPRECATED] Deactivate a subscription for the provided user context and application | DELETE account_activity/webhooks/:webhook_id/subscriptions/all | ✓ * | |
Deactivate a subscription using application-only OAuth | DELETE /account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json | ✓ | |
Redelivers activities to a webhook | POST /1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json | ✓ |
Description | **Endpoint ** | OAuth 1.0a (user context) | OAuth 2.0 Bearer Token (application-only) |
Register a new webhook URL for the given application context | POST account_activity/webhooks | ✓ | |
Return all URLs and their statuses for the given application | GET account_activity/webhooks | ✓ | |
Trigger a challenge response check (CRC) for a given webhook’s URL | PUT account_activity/webhooks/:webhook_id | ✓ | |
Subscribe the application to a user’s account events | POST account_activity/webhooks/:webhook_id/subscriptions/all | ✓ * | |
Return a count of currently active subscriptions | GET account_activity/subscriptions/count | ✓ | |
Check if a webhook configuration is subscribed to a user’s events | GET account_activity/webhooks/:webhook_id/subscriptions/all | ✓ * | |
Return a list of currently active subscriptions | GET account_activity/webhooks/:webhook_id/subscriptions/all/list | ✓ | |
Delete a webhook | DELETE account_activity/webhooks/:webhook_id | ✓ | |
[DEPRECATED] Deactivate a subscription for the provided user context and application | DELETE account_activity/webhooks/:webhook_id/subscriptions/all | ✓ * | |
Deactivate a subscription using application-only OAuth | DELETE /account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json | ✓ | |
Redelivers activities to a webhook | POST /1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json | ✓ |
Enterprise
One of the benefits of the enterprise tier of the Account Activity API is a retry mechanism for webhook events. If a ‘success’ 200 HTTP response code is not received, the X server will initiate a retry mechanism, resending the webhook event up to three times over a five-minute period. This webhook event retry service helps provide reliability and event recovery when network problems occur and during client-side service interruptions and deploys.
Activity created, POST to the webhook URL from Account Activity API and times out in three seconds. |
Wait three seconds after previous timeout finishes, then POST to the webhook URL from Account Activity API and times out in three seconds. |
Wait 27 seconds after previous timeout finishes, then POST to the webhook URL from Account Activity API and times out in three seconds. |
Wait 242 seconds after previous timeout finishes, then POST to the webhook URL from Account Activity API and times out in three seconds |
The Account Activity API will stop attempting to POST after this. Client must use other X endpoints to recover data. |
Object | Details |
---|---|
for_user_id | Identifies the user subscription subscribed that the event is related to. |
is_blocked_by | (conditional) Shown only when another user mentions your subscribed user. Included if true for Post mention events only. |
source | The user that is performing the activity. For example, the user that is following, blocking, or muting is the source user. |
target | The user that the activity applies to. For example, the user that is being followed, blocked, or muted is the target user. |
Message Type | Details |
---|---|
tweet_create_events | Post status payload when any of the following actions are taken by or to the subscription user: Posts, Retweets, Replies, @mentions, QuoteTweets, Retweet of Quote Tweets. |
favorite_events | Favorite (like) event status with the user and target. |
follow_events | Follow event with the user and target. |
unfollow_events | Unfollow event with the user and target. |
block_events | Block event with the user and target. |
unblock_events | Unblock event with the user and target. |
mute_events | Mute event with the user and target. |
unmute_events | Unmute event with the user and target. |
user_event | Revoke events sent when a user removes application authorization and subscription is automatically deleted. |
direct_message_events | Direct message status with the user and target when a direct message is sent or received. |
direct_message_indicate_typing_events | Direct message typing event with the user and target. |
direct_message_mark_read_events | Direct message read event with the user and target. |
tweet_delete_events | Notice of deleted Posts to make it easier to maintain compliance. |
Enterprise
The Account Activity Replay API is a data recovery tool that allows you to retrieve events from as far back as five days. It should be utilized to recover data in scenarios where your webhook server misses events, — whether due to disconnections lasting longer than the retry window, or for those disaster recovery scenarios where you need a few days to restore your system back to normal.
The Account Activity Replay API was developed for any scenario where you fail to ingest activities for a period of time. It delivers activities to the same webhook used for the original real-time delivery of activities. This product is a recovery tool and not a backfill tool, which means events will only be replayed if a previous delivery of them was attempted. The Account Activity Replay API cannot deliver events for a time period prior to a subscription’s creation time.
Message Type | Details |
---|---|
tweet_create_events | Post status payload when any of the following actions are taken by or to the subscription user: Posts, Retweets, Replies, @mentions, QuoteTweets |
favorite_events | Favorite (like) event status with the user and target. |
follow_events | Follow event with the user and target. |
block_events | Block event with the user and target. |
mute_events | Mute event with the user and target. |
direct_message_events | Direct message status with the user and target. |
direct_message_indicate_typing_events | Direct message typing event with the user and target. |
direct_message_mark_read_events | Direct message read event with the user and target. |
Blank lines | Blank lines will no longer be delivered in the Account Activity API as they were used as keep-alive messages in User Streams and Site Streams. |
Limit notices | Limit notices will no longer be sent to a given webhook. Instead, users can call the API to get current usage of available handles. This will be included in the developer portal at some time in the future. |
Disconnect messages | Disconnect notices will no longer be necessary as webhooks do not rely on an active connection. |
Stall warnings | Stall warnings will no longer be necessary as webhooks do not rely on an active connection being able to handle large numbers of incoming messages. |
Friends list | Friends lists will no longer be sent proactively. There will now be a REST endpoint to get this information. |
Description | Event Name | Source | Target | Target Object |
User deletes a Post | delete | Current user | Current User | Post |
Followed user deletes a Post | delete | Followed user | Followed user | Post |
User unfavorites a Post | unfavorite | Current user | Post author | Post |
User’s Post is unfavorited | unfavorite | Unfavoriting user | Current user | Post |
User unfollows someone | unfollow | Current user | Followed user | Null |
User creates a list | list_created | Current user | Current user | List |
User deletes a list | list_destroyed | Current user | Current user | List |
User edits a list | list_updated | Current user | Current user | List |
User adds someone to a list | list_member_added | Current user | Added user | List |
User is added to a list | list_member_added | Adding user | Current user | List |
User removes someone from a list | list_member_removed | Current user | Removed user | List |
User is removed from a list | list_member_removed | Removing user | Current user | List |
User subscribes to a list | list_user_subscribed | Current user | List owner | List |
User’s list is subscribed to | list_user_subscribed | Subscribing user | Current user | List |
User unsubscribes from a list | list_user_unsubscribed | Current user | List owner | List |
User’s list is unsubscribed from | list_user_unsubscribed | Unsubscribing user | Current user | List |
User updates their profile | user_update | Current user | Current user | Null |
User updates their protected status | user_update | Current user | Current user | Null |
/all/
portion of the following endpoint with other account activity data objects to limit the activities the API delivers? **POST https://api.x.com/1.1/account_activity/all/:env_name/subscriptions.json
No, this is not possible. As it currently stands, we only have the /all/
product available.
**Is there any way of using the Account Activity API without requesting Direct Messages permissions from users? **
At this point, Direct Messages permissions are required because there is no way to ‘filter out’ the Direct Messages activities for this API.
Is there a free version of the Account Activity API?
Yes, we offer the sandbox version as a free tier. Our sandbox option is limited to a single webhook with a limit of a maximum of 15 subscriptions. You can read more about the sandbox option in our documentation.
**Is it possible to use the Account Activity API to get Retweets of Posts that mention subscribed users? **
Unfortunately, this is not part of the activities delivered with this API. For this, we suggest using the Streaming API instead.
What are the possible activity types that are represented by a tweet_create_event?
A tweet_create_event payload will be sent:
If the subscription user does any of the following actions:
oauth nonce
, oauth_signature
, and oauth_timestamp
.
:env_name
is case sensitive.
Purpose | Enterprise |
Registers a webhook URL / Generates a webhook_id | POST webhooks |
Returns all webhook URLs and their statuses | GET webhooks |
Manually triggers a challenge response check | PUT webhooks/:webhook_id |
Subscribes an application to an account’s events | POST webhooks/:webhook_id/subscriptions/all |
Returns a count of currently active subscriptions | GET subscriptions/count |
Check to see if a webhook is subscribed to an account | GET webhooks/:webhook_id/subscriptions/all |
Returns a list of currently active subscriptions | GET webhooks/:webhook_id/subscriptions/all/list |
Deletes the webhook | DELETE webhooks/:webhook_id |
Deactivates a subscription using 3-legged OAuth (DEPRECATED) | DELETE webhooks/:webhook_id/subscriptions/all |
Deactivates a subscription using application-only OAuth | DELETE webhooks/:webhook_id/subscriptions/:user_id/all.json |
Redelivers activities to a webhook | POST replay/webhooks/:webhook_id/subscriptions/all |
https://api.x.com/1.1/account_activity/webhooks.json
Response Format | JSON |
Requires Authentication | Yes (user context - all consumer and access tokens) |
Rate Limited | Yes |
Requests / 15-min window (user auth) | 15 |
Support for Tweet edits | All Tweet objects will include Tweet edit metadata describing the Tweet’s edit history. See the “Tweet edits” fundamentals page for more details. |
url (required) | Encoded URL for the callback endpoint. |
HTTP Code | Message |
---|---|
200 | Webhook URL is registered to the provided application |
403 | There is an error with your request. See error messages section below. |
Code | Message |
---|---|
214 | Webhook URL does not meet the requirements. |
214 | Too many resources already created. |
214 | Webhook URL does not meet the requirements. Invalid CRC token or json response format. |
214 | High latency on CRC GET request. Your webhook should respond in less than 3 seconds. |
214 | Non-200 response code during CRC GET request (i.e. 404, 500, etc). |
https://api.x.com/1.1/account_activity/webhooks.json
Response Format | JSON |
Requires Authentication | Yes (application only - bearer token) |
Rate Limited | Yes |
Requests / 15-min window (application auth) | 15 |
Code | Message |
---|---|
99 | You don’t have access to this resource. |
valid
.
https://api.x.com/1.1/account_activity/webhooks/:webhook_id.json
Response Format | JSON |
Requires Authentication | Yes (user context - all consumer and access tokens) |
Rate Limited | Yes |
Requests / 15-min window (user auth) | 15 |
webhook_id (required) | Webhook ID. Defined in resource path. |
Code | Message |
---|---|
34 | Webhook does not exist or is associated with a different X application. |
214 | Webhook URL does not meet the requirements. |
214 | Webhook URL does not meet the requirements. Invalid CRC token or json response format. |
214 | High latency on CRC GET request. Your webhook should respond in less than 3 seconds. |
214 | Non-200 response code during CRC GET request (i.e. 404, 500, etc). |
https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json
Response Format | JSON |
Requires Authentication | Yes (3-legged OAuth - Whitelisted consumer key and subscribing user’s access token) |
Rate Limited | Yes |
Requests / 15-min window (user auth) | 500 |
webhook_id (required) | Webhook ID. Defined in resource path. |
Code | Message |
---|---|
34 | Webhook does not exist or is associated with a different X application. |
348 | Client application is not permitted to access this user’s webhook subscriptions. |
https://api.x.com/1.1/account_activity/subscriptions/count.json
Response Format | HTTP response code |
Requires Authentication | Yes (application only - bearer token) |
Rate Limited | Yes |
Requests / 15-min window (application auth) | 15 |
Code | Message |
200 | Success. A count of subscriptions for the requested webhook will be returned. |
401 | Your application does not have permission to view subscriptions for the specified webhook. |
Code | Message |
---|---|
32 | Could not authenticate you. |
https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json
Response Format | JSON |
Requires Authentication | Yes (3-legged OAuth - Whitelisted consumer key and subscribing user’s access token) |
Rate Limited | Yes |
Requests / 15-min window (user auth) | 500 |
webhook_id (required) | Webhook ID. Defined in resource path. |
https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all/list.json
Response Format | HTTP response code |
Requires Authentication | Yes (application only - bearer token) |
Rate Limited | Yes |
Requests / 15-min window (application auth) | 50 |
webhook_id (required) | Webhook ID. Defined in resource path. |
Code | Message |
---|---|
200 | Success. A list of subscriptions for the requested webhook will be returned. |
401 | Your application does not have permission to view subscriptions for the specified webhook. |
Code | Message |
---|---|
32 | Could not authenticate you. |
https://api.x.com/1.1/account_activity/webhooks/:webhook_id.json
Response Format | JSON |
Requires Authentication | Yes (user context - all consumer and access tokens) |
Rate Limited | Yes |
Requests / 15-min window (user auth) | 15 |
webhook_id (required) | Webhook ID. Defined in resource path. |
https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json
Response Format | JSON |
Requires Authentication | Yes (3-legged OAuth - Whitelisted consumer key and subscribed user’s access token) |
Rate Limited | Yes |
Requests / 15-min window (user auth) | 500 |
webhook_id (required) | Webhook ID. Defined in resource path. |
https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json
Response Format | JSON |
Requires Authentication | Yes (application only - bearer token) |
Rate Limited | Yes |
Requests / 15-min window | 500 |
Code | Message |
---|---|
404 | Sorry, that page does not exist. - This often occurs when the specified user id is not actually subscribed. |
Request Method | HTTP POST |
URL | /1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json?from_date=yyyymmddhhmm&to_date=yyyymmddhhmm |
Response Format | JSON |
Requires Authentication | Yes (application only - bearer token) |
Rate Limit | 5 requests per 15 minutes. There is currently no maximum on the number of replay jobs that can requested. |
from_date | The oldest (starting) UTC timestamp from which the events will be provided, must be in ‘yyyymmddhhmm’ format. Timestamp is in minute granularity and is inclusive (i.e. 12:00 includes the 00 minute). Valid times must be within the last 5 days, UTC time, and no more recent than 31 minutes before the current point in time. It’s recommended that the from_date and to_date should be within ~2 hours. |
to_date | The latest (ending) UTC timestamp to which the event will be provided, must be in ‘yyyymmddhhmm’ format. Timestamp is in minute granularity and is exclusive (i.e. 12:30 does not include the 30th minute of the hour). Valid times must be within the last 5 days, UTC time, and no more recent than 10 minutes before the current point in time. |
Status | Text | Error Code | Description | Message |
---|---|---|---|---|
202 | Accepted | N/A | The request was successful and the activities will be sent. | N/A |
400 | Bad Request | 214 | Webhook has been marked as invalid. | Webhook is marked invalid and requires a CRC check. |
400 | Bad Request | 357 | Query parameter is missing. | : queryParam is required. |
400 | Bad Request | 358 | Route or query parameter is malformed. | Unable to parse parameter. |
400 | Bad Request | 360 | Route parameter is negative. | webhook_id: [] is not greater than or equal to 0. |
400 | Bad Request | 368 | from_date or to_date is not in the past. | : [<field_value>] is not in the past. |
400 | Bad Request | 356 | from_date must be before to_date. | from_date must be before to_date. |
400 | Bad Request | 356 | from_date must be within the past 5 days. | from_date must be within the past 5 days. |
401 | Unauthorized | 32 | HTTP authentication failed due to 3-legged auth provided. | Invalid authentication method. Please use application-only authentication. |
401 | Unauthorized | 61 | Client is not permitted to request this method. | Client is not permitted to request this method. |
403 | Forbidden | 200 | Client does not have an enterprise account with Replay enabled. | Account Activity API enterprise account with replay is required. Please confirm you have an enterprise account and replay is enabled. |
404 | Not Found | 34 | Non-existing webhook_id; webhook_id-application_id mismatch. | Webhook does not exist or is associated with a different X application. |
409 | Conflict | 355 | There is a request in flight and it will need to finish processing before making another. | A replay job is already in progress for this webhook. |
429 | Too Many Requests | 88 | Rate limited (hit limit of the number of requests per time period) | Too many requests. Please back off your API request rate. |
500 | Internal Server Error | 0 | Internal server error. | Internal server error. |
503 | Service Unavailable | 67 | One or more dependent services at X is unavailable. | X server error. Retry using an exponential backoff pattern. |