Twitter/X Likes API
The Likes API from Twitter/X — 2 operation(s) for likes.
OpenAPI Specification
openapi: 3.0.0
info:
description: X API v2 available endpoints
version: '2.166'
title: X API v2 Account Activity Likes 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: Likes
paths:
/2/likes/firehose/stream:
get:
security:
- BearerToken: []
tags:
- Likes
summary: Stream all Likes
description: Streams all public Likes in real-time.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/tweets/filtered-stream/api-reference/get-likes-firehose-stream
operationId: streamLikesFirehose
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: partition
in: query
description: The partition number.
required: true
schema:
type: integer
minimum: 1
maximum: 20
format: int32
style: form
- name: start_time
in: query
description: YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Likes will be provided.
required: false
example: '2021-02-14T18: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 to which the Posts will be provided.
required: false
example: '2021-02-14T18:40:40.000Z'
schema:
type: string
format: date-time
style: form
- $ref: '#/components/parameters/LikeWithTweetAuthorFieldsParameter'
- $ref: '#/components/parameters/LikeWithTweetAuthorExpansionsParameter'
- $ref: '#/components/parameters/MediaFieldsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/TweetFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/StreamingLikeResponseV2'
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/likes/sample10/stream:
get:
security:
- BearerToken: []
tags:
- Likes
summary: Stream sampled Likes
description: Streams a 10% sample of public Likes in real-time.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/likes/firehose/api-reference/get-likes-sample10-stream
operationId: streamLikesSample10
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: partition
in: query
description: The partition number.
required: true
schema:
type: integer
minimum: 1
maximum: 2
format: int32
style: form
- name: start_time
in: query
description: YYYY-MM-DDTHH:mm:ssZ. The earliest UTC timestamp to which the Likes will be provided.
required: false
example: '2021-02-14T18: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 to which the Posts will be provided.
required: false
example: '2021-02-14T18:40:40.000Z'
schema:
type: string
format: date-time
style: form
- $ref: '#/components/parameters/LikeWithTweetAuthorFieldsParameter'
- $ref: '#/components/parameters/LikeWithTweetAuthorExpansionsParameter'
- $ref: '#/components/parameters/MediaFieldsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/TweetFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/StreamingLikeResponseV2'
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
components:
schemas:
StreamingLikeResponseV2:
type: object
properties:
data:
$ref: '#/components/schemas/LikeWithTweetAuthor'
errors:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Problem'
includes:
$ref: '#/components/schemas/Expansions'
HashtagEntity:
allOf:
- $ref: '#/components/schemas/EntityIndicesInclusiveExclusive'
- $ref: '#/components/schemas/HashtagFields'
PlaceId:
type: string
description: The identifier for this place.
example: f7eb2fa2fea288b1
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.
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'
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'
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'
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'
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
PlaceType:
type: string
enum:
- poi
- neighborhood
- city
- admin
- country
- unknown
example: city
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
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
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'
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.
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/EntityIndicesInclusiveInclusive'
- type: object
description: Represents the data for the annotation.
properties:
normalized_text:
type: string
description: Text used to determine annotation.
example: Barack Obama
probability:
type: number
description: Confidence factor for annotation type.
minimum: 0
maximum: 1
format: double
type:
type: string
description: Annotation type.
example: Person
cashtags:
type: array
minItems: 1
items:
$ref: '#/components/schemas/CashtagEntity'
hashtags:
type: array
minItems: 1
items:
$ref: '#/components/schemas/HashtagEntity'
mentions:
type: array
minItems: 1
items:
$ref: '#/components/schemas/MentionEntity'
urls:
type: array
minItems: 1
items:
$ref: '#/components/schemas/UrlEntity'
MediaKey:
type: string
description: The Media Key identifier for this attachment.
pattern: ^([0-9]+)_([0-9]+)$
TweetText:
type: string
description: The content of the Tweet.
example: Learn how to use the user Tweet timeline and user mention timeline endpoints in the X API v2 to explore Tweet\u2026 https:\/\/t.co\/56a0vZUx7i
TweetId:
type: string
description: Unique identifier of this Tweet. 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: '1346889436626259968'
MediaHeight:
type: integer
description: The height of the media in pixels.
minimum: 0
NoteTweetText:
type: string
description: The note content of the Tweet.
example: Learn how to use the user Tweet timeline and user mention timeline endpoints in the X API v2 to explore Tweet\u2026 https:\/\/t.co\/56a0vZUx7i
Point:
type: object
description: A [GeoJson Point](https://tools.ietf.org/html/rfc7946#section-3.1.2) geometry object.
required:
- type
- coordinates
properties:
coordinates:
$ref: '#/components/schemas/Position'
type:
type: string
enum:
- Point
example: Point
HttpStatusCode:
type: integer
description: HTTP Status Code.
minimum: 100
maximum: 599
DisplayTextRange:
type: array
description: Represent a boundary range (start and end zero-based indices) for the portion of text that is displayed for a post. `start` must be smaller than `end`. The start index is inclusive, the end index is exclusive.
minItems: 2
maxItems: 2
items:
type: integer
minimum: 0
UrlEntity:
description: Represent the portion of text recognized as a URL, and its start and end position within the text.
allOf:
- $ref: '#/components/schemas/EntityIndicesInclusiveExclusive'
- $ref: '#/components/schemas/UrlFields'
Place:
type: object
required:
- id
- full_name
properties:
contained_within:
type: array
minItems: 1
items:
$ref: '#/components/schemas/PlaceId'
country:
type: string
description: The full name of the county in which this place exists.
example: United States
country_code:
$ref: '#/components/schemas/CountryCode'
full_name:
type: string
description: The full name of this place.
example: Lakewood, CO
geo:
$ref: '#/components/schemas/Geo'
id:
$ref: '#/components/schemas/PlaceId'
name:
type: string
description: The human readable name of this place.
example: Lakewood
place_type:
$ref: '#/components/schemas/PlaceType'
TweetWithheld:
type: object
description: Indicates withholding details for [withheld content](https://help.twitter.com/en/rules-and-policies/tweet-withheld-by-country).
required:
- copyright
- country_codes
properties:
copyright:
type: boolean
description: Indicates if the content is being withheld for on the basis of copyright infringement.
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 whether the content being withheld is the `tweet` or a `user`.
enum:
- tweet
- user
Position:
type: array
description: A [GeoJson Position](https://tools.ietf.org/html/rfc7946#section-3.1.1) in the format `[longitude,latitude]`.
minItems: 2
maxItems: 2
items:
type: number
example:
- -105.18816086351444
- 40.247749999999996
TopicId:
type: string
description: Unique identifier of this Topic.
CountryCode:
type: string
description: A two-letter ISO 3166-1 alpha-2 country code.
pattern: ^[A-Z]{2}$
example: US
Topic:
type: object
description: The topic of a Space, as selected by its creator.
required:
- id
- name
properties:
description:
type: string
description: The description of the given topic.
example: All about technology
id:
$ref: '#/components/schemas/TopicId'
name:
type: string
description: The name of the given topic.
example: Technology
UrlFields:
type: object
description: Represent the portion of text recognized as a URL.
required:
- url
properties:
description:
type: string
description: Description of the URL landing page.
example: This is a description of the website.
display_url:
type: string
description: The URL as displayed in the X client.
example: twittercommunity.com/t/introducing-…
expanded_url:
$ref: '#/components/schemas/Url'
images:
type: array
minItems: 1
items:
$ref: '#/components/schemas/UrlImage'
media_key:
$ref: '#/components/schemas/MediaKey'
status:
$ref: '#/components/schemas/HttpStatusCode'
title:
type: string
description: Title of the page the URL points to.
example: Introducing the v2 follow lookup endpoints
unwound_url:
type: string
description: Fully resolved url.
format: uri
example: https://twittercommunity.com/t/introducing-the-v2-follow-lookup-endpoints/147118
url:
$ref: '#/components/schemas/Url'
PollOptionLabel:
type: string
description: The text of a poll choice.
minLength: 1
maxLength: 25
EntityIndicesInclusiveExclusive:
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 exclusive.
required:
- start
- end
properties:
end:
type: integer
description: Index (zero-based) at which position this entity ends. The index is exclusive.
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
LikeId:
type: string
description: The unique identifier of this Like.
pattern: ^[A-Za-z0-9_]{1,40}$
example: 8ba4f34e6235d905a46bac021d98e923
Url:
type: string
description: A validly formatted URL.
format: uri
example: https://developer.twitter.com/en/docs/twitter-api
Tweet:
type: object
properties:
attachments:
type: object
description: Specifies the type of attachments (if any) present in this Tweet.
properties:
media_keys:
type: array
description: A list of Media Keys for each one of the media attachments (if media are attached).
minItems: 1
items:
$ref: '#/components/schemas/MediaKey'
media_source_tweet_id:
type: array
description: A list of Posts the media on this Tweet was originally posted in. For example, if the media on a tweet is re-used in another Tweet, this refers to the original, source Tweet..
minItems: 1
items:
$ref: '#/components/schemas/TweetId'
poll_ids:
type: array
description: A list of poll IDs (if polls are attached).
minItems: 1
items:
$ref: '#/components/schemas/PollId'
author_id:
$ref: '#/components/schemas/UserId'
community_id:
$ref: '#/components/schemas/CommunityId'
context_annotations:
type: array
minItems: 1
items:
# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/twitter-x/refs/heads/main/openapi/twitter-x-likes-api-openapi.yml