Twitter/X Activity API
The Activity API from Twitter/X — 3 operation(s) for activity.
The Activity API from Twitter/X — 3 operation(s) for activity.
openapi: 3.0.0
info:
description: X API v2 available endpoints
version: '2.166'
title: X API v2 Account Activity API
termsOfService: https://developer.x.com/en/developer-terms/agreement-and-policy.html
contact:
name: X Developers
url: https://developer.x.com/
license:
name: X Developer Agreement and Policy
url: https://developer.x.com/en/developer-terms/agreement-and-policy.html
servers:
- description: X API
url: https://api.x.com
tags:
- name: Activity
paths:
/2/activity/stream:
get:
security:
- BearerToken: []
tags:
- Activity
summary: Activity Stream
description: Stream of X Activities
externalDocs:
url: https://docs.x.com/x-api/activity/activity-stream
operationId: activityStream
parameters:
- name: backfill_minutes
in: query
description: The number of minutes of backfill requested.
required: false
schema:
type: integer
minimum: 0
maximum: 5
format: int32
style: form
- name: start_time
in: query
description: YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp from which the Post labels will be provided.
required: false
example: '2021-02-01T18:40:40.000Z'
schema:
type: string
format: date-time
style: form
- name: end_time
in: query
description: YYYY-MM-DDTHH:mm:ssZ. The latest UTC timestamp from which the Post labels will be provided.
required: false
example: '2021-02-01T18:40:40.000Z'
schema:
type: string
format: date-time
style: form
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivityStreamingResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
x-twitter-streaming: true
/2/activity/subscriptions:
delete:
security:
- BearerToken: []
tags:
- Activity
summary: Delete X activity subscriptions by IDs
description: Deletes multiple subscriptions for X activity events by their IDs
externalDocs:
url: https://docs.x.com/x-api/activity/delete-x-activity-subscriptions-by-ids
operationId: deleteActivitySubscriptionsByIds
parameters:
- name: ids
in: query
description: Comma-separated list of subscription IDs to delete.
required: true
schema:
type: array
minItems: 1
maxItems: 100
items:
$ref: '#/components/schemas/ActivitySubscriptionId'
explode: false
style: form
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivitySubscriptionDeleteResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
get:
security:
- BearerToken: []
- OAuth2UserToken:
- like.read
- tweet.read
- UserToken: []
tags:
- Activity
summary: Get X activity subscriptions
description: Get a list of active subscriptions for XAA
externalDocs:
url: https://docs.x.com/x-api/activity/get-x-activity-subscriptions
operationId: getActivitySubscriptions
parameters:
- name: max_results
in: query
description: The maximum number of results to return per page. Defaults to 1000 when unspecified; use pagination_token (from response meta.next_token) to fetch additional pages.
required: false
schema:
type: integer
minimum: 1
maximum: 1000
format: int32
default: 1000
style: form
- name: pagination_token
in: query
description: This parameter is used to get the next 'page' of results.
required: false
schema:
$ref: '#/components/schemas/PaginationToken32'
style: form
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivitySubscriptionGetResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
post:
security:
- BearerToken: []
- OAuth2UserToken:
- dm.read
- like.read
- tweet.read
- UserToken: []
tags:
- Activity
summary: Create X activity subscription
description: Creates a subscription for an X activity event
externalDocs:
url: https://docs.x.com/x-api/activity/create-x-activity-subscription
operationId: createActivitySubscription
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ActivitySubscriptionCreateRequest'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivitySubscriptionCreateResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
/2/activity/subscriptions/{subscription_id}:
delete:
security:
- BearerToken: []
tags:
- Activity
summary: Deletes X activity subscription
description: Deletes a subscription for an X activity event
externalDocs:
url: https://docs.x.com/x-api/activity/deletes-x-activity-subscription
operationId: deleteActivitySubscription
parameters:
- name: subscription_id
in: path
description: The ID of the subscription to delete.
required: true
schema:
$ref: '#/components/schemas/ActivitySubscriptionId'
style: simple
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivitySubscriptionDeleteResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
put:
security:
- BearerToken: []
tags:
- Activity
summary: Update X activity subscription
description: Updates a subscription for an X activity event
externalDocs:
url: https://docs.x.com/x-api/activity/update-x-activity-subscription
operationId: updateActivitySubscription
parameters:
- name: subscription_id
in: path
description: The ID of the subscription to update.
required: true
schema:
$ref: '#/components/schemas/ActivitySubscriptionId'
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ActivitySubscriptionUpdateRequest'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/ActivitySubscriptionUpdateResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
components:
schemas:
HashtagEntity:
allOf:
- $ref: '#/components/schemas/EntityIndicesInclusiveExclusive'
- $ref: '#/components/schemas/HashtagFields'
NewsActivityResponsePayload:
type: object
properties:
category:
type: string
headline:
type: string
hook:
type: string
summary:
type: string
additionalProperties: false
ActivitySubscriptionCreateRequest:
type: object
required:
- event_type
- filter
properties:
event_type:
type: string
enum:
- 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
- spaces.start
- spaces.end
- chat.received
- chat.sent
- chat.conversation_join
- dm.sent
- dm.received
- dm.indicate_typing
- dm.read
- post.create
- post.delete
- post.mention.create
- like.create
filter:
$ref: '#/components/schemas/ActivitySubscriptionFilter'
tag:
type: string
minLength: 1
maxLength: 200
webhook_id:
$ref: '#/components/schemas/WebhookConfigId'
additionalProperties: false
PlaceId:
type: string
description: The identifier for this place.
example: f7eb2fa2fea288b1
Keyword:
type: string
description: A keyword to filter on.
minLength: 1
maxLength: 150
example: The President
ContextAnnotationEntityFields:
type: object
description: Represents the data for the context annotation entity.
required:
- id
properties:
description:
type: string
description: Description of the context annotation entity.
id:
type: string
description: The unique id for a context annotation entity.
pattern: ^[0-9]{1,19}$
name:
type: string
description: Name of the context annotation entity.
ActivityEventId:
type: string
description: The unique identifier of an Activity event.
pattern: ^[0-9]{1,19}$
example: '1146654567674912769'
Media:
type: object
required:
- type
properties:
height:
$ref: '#/components/schemas/MediaHeight'
media_key:
$ref: '#/components/schemas/MediaKey'
type:
type: string
width:
$ref: '#/components/schemas/MediaWidth'
discriminator:
propertyName: type
mapping:
animated_gif: '#/components/schemas/AnimatedGif'
photo: '#/components/schemas/Photo'
video: '#/components/schemas/Video'
User:
type: object
description: The X User object.
required:
- id
- name
- username
properties:
affiliation:
type: object
description: Metadata about a user's affiliation.
properties:
badge_url:
type: string
description: The badge URL corresponding to the affiliation.
format: uri
description:
type: string
description: The description of the affiliation.
url:
type: string
description: The URL, if available, to details about an affiliation.
format: uri
user_id:
type: array
minItems: 1
items:
$ref: '#/components/schemas/UserId'
connection_status:
type: array
description: Returns detailed information about the relationship between two users.
minItems: 0
items:
type: string
description: Type of connection between users.
enum:
- follow_request_received
- follow_request_sent
- blocking
- followed_by
- following
- muting
created_at:
type: string
description: Creation time of this User.
format: date-time
description:
type: string
description: The text of this User's profile description (also known as bio), if the User provided one.
entities:
type: object
description: A list of metadata found in the User's profile description.
properties:
description:
$ref: '#/components/schemas/FullTextEntities'
url:
type: object
description: Expanded details for the URL specified in the User's profile, with start and end indices.
properties:
urls:
type: array
minItems: 1
items:
$ref: '#/components/schemas/UrlEntity'
id:
$ref: '#/components/schemas/UserId'
location:
type: string
description: The location specified in the User's profile, if the User provided one. As this is a freeform value, it may not indicate a valid location, but it may be fuzzily evaluated when performing searches with location queries.
most_recent_tweet_id:
$ref: '#/components/schemas/TweetId'
name:
type: string
description: The friendly name of this User, as shown on their profile.
pinned_tweet_id:
$ref: '#/components/schemas/TweetId'
profile_banner_url:
type: string
description: The URL to the profile banner for this User.
format: uri
profile_image_url:
type: string
description: The URL to the profile image for this User.
format: uri
protected:
type: boolean
description: Indicates if this User has chosen to protect their Posts (in other words, if this User's Posts are private).
public_metrics:
type: object
description: A list of metrics for this User.
required:
- followers_count
- following_count
- tweet_count
- listed_count
properties:
followers_count:
type: integer
description: Number of Users who are following this User.
following_count:
type: integer
description: Number of Users this User is following.
like_count:
type: integer
description: The number of likes created by this User.
listed_count:
type: integer
description: The number of lists that include this User.
tweet_count:
type: integer
description: The number of Posts (including Retweets) posted by this User.
receives_your_dm:
type: boolean
description: Indicates if you can send a DM to this User
subscription_type:
type: string
description: 'The X Blue subscription type of the user, eg: Basic, Premium, PremiumPlus or None.'
enum:
- Basic
- Premium
- PremiumPlus
- None
url:
type: string
description: The URL specified in the User's profile.
username:
$ref: '#/components/schemas/UserName'
verified:
type: boolean
description: Indicate if this User is a verified X User.
verified_type:
type: string
description: 'The X Blue verified type of the user, eg: blue, government, business or none.'
enum:
- blue
- government
- business
- none
withheld:
$ref: '#/components/schemas/UserWithheld'
example:
created_at: '2013-12-14T04:35:55Z'
id: '2244994945'
name: X Dev
protected: false
username: TwitterDev
LikeWithTweetAuthor:
type: object
description: A Like event, with the tweet author user and the tweet being liked
properties:
created_at:
type: string
description: Creation time of the Tweet.
format: date-time
example: '2021-01-06T18:40:40.000Z'
id:
$ref: '#/components/schemas/LikeId'
liked_tweet_id:
$ref: '#/components/schemas/TweetId'
timestamp_ms:
type: integer
description: Timestamp in milliseconds of creation.
format: int32
tweet_author_id:
$ref: '#/components/schemas/UserId'
UserName:
type: string
description: The X handle (screen name) of this user.
pattern: ^[A-Za-z0-9_]{1,15}$
MentionEntity:
allOf:
- $ref: '#/components/schemas/EntityIndicesInclusiveExclusive'
- $ref: '#/components/schemas/MentionFields'
ContextAnnotation:
type: object
description: Annotation inferred from the Tweet text.
required:
- domain
- entity
properties:
domain:
$ref: '#/components/schemas/ContextAnnotationDomainFields'
entity:
$ref: '#/components/schemas/ContextAnnotationEntityFields'
UserId:
type: string
description: Unique identifier of this User. This is returned as a string in order to avoid complications with languages and tools that cannot handle large integers.
pattern: ^[0-9]{1,19}$
example: '2244994945'
Expansions:
type: object
properties:
media:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Media'
places:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Place'
polls:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Poll'
topics:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Topic'
tweets:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Tweet'
users:
type: array
minItems: 1
items:
$ref: '#/components/schemas/User'
PollOption:
type: object
description: Describes a choice in a Poll object.
required:
- position
- label
- votes
properties:
label:
$ref: '#/components/schemas/PollOptionLabel'
position:
type: integer
description: Position of this choice in the poll.
votes:
type: integer
description: Number of users who voted for this choice.
CommunityId:
type: string
description: The unique identifier of this Community.
pattern: ^[0-9]{1,19}$
example: '1146654567674912769'
ActivitySubscriptionCreateResponse:
type: object
properties:
data:
type: object
properties:
subscription:
$ref: '#/components/schemas/ActivitySubscription'
total_subscriptions_for_instance_id:
type: integer
errors:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Problem'
meta:
type: object
properties:
total_subscriptions:
type: integer
description: Number of active subscriptions.
format: int32
EntityIndicesInclusiveInclusive:
type: object
description: Represent a boundary range (start and end index) for a recognized entity (for example a hashtag or a mention). `start` must be smaller than `end`. The start index is inclusive, the end index is inclusive.
required:
- start
- end
properties:
end:
type: integer
description: Index (zero-based) at which position this entity ends. The index is inclusive.
minimum: 0
example: 61
start:
type: integer
description: Index (zero-based) at which position this entity starts. The index is inclusive.
minimum: 0
example: 50
NoteId:
type: string
description: The unique identifier of this Community Note.
pattern: ^[0-9]{1,19}$
example: '1146654567674912769'
ReplySettingsWithVerifiedUsers:
type: string
description: Shows who can reply a Tweet. Fields returned are everyone, mentioned_users, subscribers, verified and following.
pattern: ^[A-Za-z]{1,12}$
enum:
- everyone
- mentionedUsers
- following
- other
- subscribers
- verified
CashtagFields:
type: object
description: Represent the portion of text recognized as a Cashtag, and its start and end position within the text.
required:
- tag
properties:
tag:
type: string
example: TWTR
Geo:
type: object
required:
- type
- bbox
- properties
properties:
bbox:
type: array
minItems: 4
maxItems: 4
items:
type: number
minimum: -180
maximum: 180
format: double
example:
- -105.193475
- 39.60973
- -105.053164
- 39.761974
geometry:
$ref: '#/components/schemas/Point'
properties:
type: object
type:
type: string
enum:
- Feature
PlaceType:
type: string
enum:
- poi
- neighborhood
- city
- admin
- country
- unknown
example: city
Problem:
type: object
description: An HTTP Problem Details object, as defined in IETF RFC 7807 (https://tools.ietf.org/html/rfc7807).
required:
- type
- title
properties:
detail:
type: string
status:
type: integer
title:
type: string
type:
type: string
discriminator:
propertyName: type
mapping:
about:blank: '#/components/schemas/GenericProblem'
https://api.twitter.com/2/problems/client-disconnected: '#/components/schemas/ClientDisconnectedProblem'
https://api.twitter.com/2/problems/client-forbidden: '#/components/schemas/ClientForbiddenProblem'
https://api.twitter.com/2/problems/conflict: '#/components/schemas/ConflictProblem'
https://api.twitter.com/2/problems/disallowed-resource: '#/components/schemas/DisallowedResourceProblem'
https://api.twitter.com/2/problems/duplicate-rules: '#/components/schemas/DuplicateRuleProblem'
https://api.twitter.com/2/problems/invalid-request: '#/components/schemas/InvalidRequestProblem'
https://api.twitter.com/2/problems/invalid-rules: '#/components/schemas/InvalidRuleProblem'
https://api.twitter.com/2/problems/noncompliant-rules: '#/components/schemas/NonCompliantRulesProblem'
https://api.twitter.com/2/problems/not-authorized-for-field: '#/components/schemas/FieldUnauthorizedProblem'
https://api.twitter.com/2/problems/not-authorized-for-resource: '#/components/schemas/ResourceUnauthorizedProblem'
https://api.twitter.com/2/problems/operational-disconnect: '#/components/schemas/OperationalDisconnectProblem'
https://api.twitter.com/2/problems/resource-not-found: '#/components/schemas/ResourceNotFoundProblem'
https://api.twitter.com/2/problems/resource-unavailable: '#/components/schemas/ResourceUnavailableProblem'
https://api.twitter.com/2/problems/rule-cap: '#/components/schemas/RulesCapProblem'
https://api.twitter.com/2/problems/streaming-connection: '#/components/schemas/ConnectionExceptionProblem'
https://api.twitter.com/2/problems/unsupported-authentication: '#/components/schemas/UnsupportedAuthenticationProblem'
https://api.twitter.com/2/problems/usage-capped: '#/components/schemas/UsageCapExceededProblem'
UserWithheld:
type: object
description: Indicates withholding details for [withheld content](https://help.twitter.com/en/rules-and-policies/tweet-withheld-by-country).
required:
- country_codes
properties:
country_codes:
type: array
description: Provides a list of countries where this content is not available.
minItems: 1
uniqueItems: true
items:
$ref: '#/components/schemas/CountryCode'
scope:
type: string
description: Indicates that the content being withheld is a `user`.
enum:
- user
Poll:
type: object
description: Represent a Poll attached to a Tweet.
required:
- id
- options
properties:
duration_minutes:
type: integer
minimum: 5
maximum: 10080
format: int32
end_datetime:
type: string
format: date-time
id:
$ref: '#/components/schemas/PollId'
options:
type: array
minItems: 2
maxItems: 4
items:
$ref: '#/components/schemas/PollOption'
voting_status:
type: string
enum:
- open
- closed
ActivitySubscriptionId:
type: string
description: The unique identifier of this subscription.
pattern: ^[0-9]{1,19}$
example: '1146654567674912769'
CashtagEntity:
allOf:
- $ref: '#/components/schemas/EntityIndicesInclusiveExclusive'
- $ref: '#/components/schemas/CashtagFields'
MediaWidth:
type: integer
description: The width of the media in pixels.
minimum: 0
MentionFields:
type: object
description: Represent the portion of text recognized as a User mention, and its start and end position within the text.
required:
- username
properties:
id:
$ref: '#/components/schemas/UserId'
username:
$ref: '#/components/schemas/UserName'
PostDeleteActivityResponsePayload:
type: object
description: The identity of a deleted Post.
required:
- id
- author_id
properties:
author_id:
$ref: '#/components/schemas/UserId'
id:
$ref: '#/components/schemas/TweetId'
additionalProperties: false
ActivitySubscriptionGetResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/ActivitySubscription'
errors:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Problem'
meta:
type: object
properties:
next_token:
type: string
description: Token to retrieve the next page of results.
result_count:
type: integer
description: Number of active subscriptions returned in response.
format: int32
ActivityStreamingResponsePayload:
oneOf:
- $ref: '#/components/schemas/ProfileUpdateActivityResponsePayload'
- $ref: '#/components/schemas/NewsActivityResponsePayload'
- $ref: '#/components/schemas/FollowActivityResponsePayload'
- $ref: '#/components/schemas/Tweet'
- $ref: '#/components/schemas/PostDeleteActivityResponsePayload'
- $ref: '#/components/schemas/LikeWithTweetAuthor'
discriminator:
propertyName: ../event_type
mapping:
follow.follow: '#/components/schemas/FollowActivityResponsePayload'
follow.unfollow: '#/components/schemas/FollowActivityResponsePayload'
like.create: '#/components/schemas/LikeWithTweetAuthor'
news.new: '#/components/schemas/NewsActivityResponsePayload'
post.create: '#/components/schemas/Tweet'
post.delete: '#/components/schemas/PostDeleteActivityResponsePayload'
post.mention.create: '#/components/schemas/Tweet'
profile.update.affiliate_badge: '#/components/schemas/ProfileUpdateActivityResponsePayload'
profile.update.banner_picture: '#/components/schemas/ProfileUpdateActivityResponsePayload'
profile.update.bio: '#/components/schemas/ProfileUpdateActivityResponsePayload'
profile.update.geo: '#/components/schemas/ProfileUpdateActivityResponsePayload'
profile.update.handle: '#/components/schemas/ProfileUpdateActivityResponsePayload'
profile.update.profile_picture: '#/components/schemas/ProfileUpdateActivityResponsePayload'
profile.update.screenname: '#/components/schemas/ProfileUpdateActivityResponsePayload'
profile.update.url: '#/components/schemas/ProfileUpdateActivityResponsePayload'
profile.update.verified_badge: '#/components/schemas/ProfileUpdateActivityResponsePayload'
ActivitySubscriptionFilter:
type: object
description: An XAA subscription filter.
properties:
direction:
type: string
description: Optional direction filter for directional events.
enum:
- inbound
- outbound
keyword:
$ref: '#/components/schemas/Keyword'
user_id:
$ref: '#/components/schemas/UserId'
additionalProperties: false
ContextAnnotationDomainFields:
type: object
description: Represents the data for the context annotation domain.
required:
- id
properties:
description:
type: string
description: Description of the context annotation domain.
id:
type: string
description: The unique id for a context annotation domain.
pattern: ^[0-9]{1,19}$
name:
type: string
description: Name of the context annotation domain.
ActivitySubscription:
type: object
description: An XActivity subscription.
required:
- subscription_id
- event_type
- filter
- created_at
- updated_at
properties:
created_at:
type: string
format: date-time
event_type:
type: string
filter:
$ref: '#/components/schemas/ActivitySubscriptionFilter'
subscription_id:
$ref: '#/components/schemas/ActivitySubscriptionId'
tag:
type: string
updated_at:
type: string
format: date-time
webhook_id:
$ref: '#/components/schemas/WebhookConfigId'
UrlImage:
type: object
description: Represent the information for the URL image.
properties:
height:
$ref: '#/components/schemas/MediaHeight'
url:
$ref: '#/components/schemas/Url'
width:
$ref: '#/components/schemas/MediaWidth'
HashtagFields:
type: object
description: Represent the portion of text recognized as a Hashtag, and its start and end position within the text.
required:
- tag
properties:
tag:
type: string
description: The text of the Hashtag.
example: MondayMotivation
FullTextEntities:
type: object
properties:
annotations:
type: array
minItems: 1
items:
description: Annotation for entities based on the Tweet text.
allOf:
- $ref: '#/components/schemas/EntityIndicesInclusiveInclusi
# --- truncated at 32 KB (55 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/twitter-x/refs/heads/main/openapi/twitter-x-activity-api-openapi.yml