X Posts API
Endpoints related to retrieving, searching, and modifying Posts — 14 operation(s) in the X-published contract.
Endpoints related to retrieving, searching, and modifying Posts — 14 operation(s) in the X-published contract.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/x-posts-api"
curl "https://apis.io/api/v1/apis?limit=25"
Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: X Posts API
version: '1.0'
description: 'Operations tagged Posts across 2 of this provider''s published API definitions: x-api-v2-openapi.json, x-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- description: X API
url: https://api.x.com
- url: https://api.x.com/2
description: X API v2 production server
tags:
- name: Posts
description: Endpoints related to retrieving, searching, and modifying Posts
externalDocs:
description: Find out more
url: https://docs.x.com/x-api/posts/introduction
paths:
/2/tweets:
get:
security:
- OAuth2UserToken:
- tweet.read
- users.read
- UserToken: []
- BearerToken: []
tags:
- Posts
summary: Get Posts by IDs
operationId: getPostsByIds
parameters:
- name: ids
in: query
required: true
schema:
type: array
minItems: 1
maxItems: 100
items:
$ref: '#/components/schemas/PostId'
explode: false
style: form
- $ref: '#/components/parameters/PostFieldsParameter'
- $ref: '#/components/parameters/PostExpansionsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/MediaFieldsParameter'
- $ref: '#/components/parameters/PollFieldsParameter'
- $ref: '#/components/parameters/PlaceFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/GetPostsByIdsResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
post:
security:
- OAuth2UserToken:
- tweet.read
- users.read
- tweet.write
- UserToken: []
tags:
- Posts
summary: Create Posts
operationId: createPosts
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePostsRequest'
required: true
responses:
'201':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePostsResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
servers:
- description: X API
url: https://api.x.com
/2/tweets/analytics:
get:
security:
- OAuth2UserToken:
- tweet.read
- users.read
- UserToken: []
tags:
- Posts
summary: Get Posts Analytics
operationId: getPostsAnalytics
parameters:
- name: ids
in: query
required: true
schema:
type: array
minItems: 1
maxItems: 100
items:
$ref: '#/components/schemas/AnalyticsId'
explode: false
style: form
- name: start_time
in: query
required: true
schema:
type: string
format: date-time
style: form
- name: end_time
in: query
required: true
schema:
type: string
format: date-time
style: form
- name: granularity
in: query
required: false
schema:
type: string
enum:
- hourly
- weekly
- daily
- total
default: total
style: form
- $ref: '#/components/parameters/AnalyticsFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/GetPostsAnalyticsResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
servers:
- description: X API
url: https://api.x.com
/2/tweets/counts/all:
get:
security:
- BearerToken: []
tags:
- Posts
summary: Get Posts Counts All
description: At most one of `pagination_token`, `next_token` may be provided.
operationId: getPostsCountsAll
parameters:
- name: query
in: query
required: true
schema:
type: string
minLength: 1
maxLength: 4096
style: form
- name: start_time
in: query
required: false
schema:
type: string
format: date-time
style: form
- name: end_time
in: query
required: false
schema:
type: string
format: date-time
style: form
- name: since_id
in: query
required: false
schema:
type: string
pattern: ^[0-9]{1,19}$
style: form
- name: until_id
in: query
required: false
schema:
type: string
pattern: ^[0-9]{1,19}$
style: form
- name: next_token
in: query
description: A base32hex-encoded pagination token.
required: false
schema:
type: string
minLength: 1
style: form
- name: pagination_token
in: query
description: A base32hex-encoded pagination token.
required: false
schema:
type: string
minLength: 1
style: form
- name: granularity
in: query
required: false
schema:
type: string
enum:
- minute
- hour
- day
default: hour
style: form
- name: search_count.fields
in: query
required: false
schema:
type: string
style: form
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/GetPostsCountsAllResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
servers:
- description: X API
url: https://api.x.com
/2/tweets/counts/recent:
get:
security:
- OAuth2UserToken: []
- BearerToken: []
tags:
- Posts
summary: Get Posts Counts Recent
description: At most one of `pagination_token`, `next_token` may be provided.
operationId: getPostsCountsRecent
parameters:
- name: query
in: query
required: true
schema:
type: string
minLength: 1
maxLength: 4096
style: form
- name: start_time
in: query
description: Must be within the last 7 days.
required: false
schema:
type: string
format: date-time
style: form
- name: end_time
in: query
required: false
schema:
type: string
format: date-time
style: form
- name: since_id
in: query
required: false
schema:
type: string
pattern: ^[0-9]{1,19}$
style: form
- name: until_id
in: query
required: false
schema:
type: string
pattern: ^[0-9]{1,19}$
style: form
- name: next_token
in: query
description: A base32hex-encoded pagination token.
required: false
schema:
type: string
minLength: 1
style: form
- name: pagination_token
in: query
description: A base32hex-encoded pagination token.
required: false
schema:
type: string
minLength: 1
style: form
- name: granularity
in: query
required: false
schema:
type: string
enum:
- minute
- hour
- day
default: hour
style: form
- name: search_count.fields
in: query
required: false
schema:
type: string
style: form
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/GetPostsCountsRecentResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
servers:
- description: X API
url: https://api.x.com
/2/tweets/search/all:
get:
security:
- OAuth2UserToken:
- users.read
- tweet.read
- UserToken: []
- BearerToken: []
tags:
- Posts
summary: Search Posts All
description: At most one of `start_time`, `since_id` may be provided. At most one of `end_time`, `until_id` may be provided. At most one of `pagination_token`, `next_token` may be provided.
operationId: searchPostsAll
parameters:
- name: query
in: query
required: true
schema:
type: string
minLength: 1
maxLength: 4096
style: form
- name: start_time
in: query
required: false
schema:
type: string
format: date-time
style: form
- name: end_time
in: query
required: false
schema:
type: string
format: date-time
style: form
- name: since_id
in: query
required: false
schema:
type: string
pattern: ^[0-9]{1,19}$
style: form
- name: until_id
in: query
required: false
schema:
type: string
pattern: ^[0-9]{1,19}$
style: form
- name: max_results
in: query
required: false
schema:
type: integer
minimum: 10
maximum: 500
format: int32
default: 10
style: form
- name: next_token
in: query
description: A base32hex-encoded pagination token.
required: false
schema:
type: string
minLength: 1
style: form
- name: pagination_token
in: query
description: A base32hex-encoded pagination token.
required: false
schema:
type: string
minLength: 1
style: form
- name: sort_order
in: query
required: false
schema:
type: string
enum:
- recency
- relevancy
style: form
- $ref: '#/components/parameters/PostFieldsParameter'
- $ref: '#/components/parameters/PostExpansionsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/MediaFieldsParameter'
- $ref: '#/components/parameters/PollFieldsParameter'
- $ref: '#/components/parameters/PlaceFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchPostsAllResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
servers:
- description: X API
url: https://api.x.com
/2/tweets/search/recent:
get:
security:
- OAuth2UserToken:
- users.read
- tweet.read
- UserToken: []
- BearerToken: []
tags:
- Posts
summary: Search Posts Recent
description: At most one of `start_time`, `since_id` may be provided. At most one of `end_time`, `until_id` may be provided. At most one of `pagination_token`, `next_token` may be provided.
operationId: searchPostsRecent
parameters:
- name: query
in: query
required: true
schema:
type: string
minLength: 1
maxLength: 4096
style: form
- name: max_results
in: query
required: false
schema:
type: integer
minimum: 10
maximum: 100
format: int32
default: 10
style: form
- name: next_token
in: query
description: A base32hex-encoded pagination token.
required: false
schema:
type: string
minLength: 1
style: form
- name: pagination_token
in: query
description: A base32hex-encoded pagination token.
required: false
schema:
type: string
minLength: 1
style: form
- name: start_time
in: query
description: Must be within the last 7 days.
required: false
schema:
type: string
format: date-time
style: form
- name: end_time
in: query
required: false
schema:
type: string
format: date-time
style: form
- name: since_id
in: query
required: false
schema:
type: string
pattern: ^[0-9]{1,19}$
style: form
- name: until_id
in: query
required: false
schema:
type: string
pattern: ^[0-9]{1,19}$
style: form
- name: sort_order
in: query
required: false
schema:
type: string
enum:
- recency
- relevancy
style: form
- $ref: '#/components/parameters/PostFieldsParameter'
- $ref: '#/components/parameters/PostExpansionsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/MediaFieldsParameter'
- $ref: '#/components/parameters/PollFieldsParameter'
- $ref: '#/components/parameters/PlaceFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/SearchPostsRecentResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
servers:
- description: X API
url: https://api.x.com
/2/tweets/{id}:
delete:
security:
- OAuth2UserToken:
- users.read
- tweet.read
- tweet.write
- UserToken: []
tags:
- Posts
summary: Delete Posts
operationId: deletePosts
parameters:
- name: id
in: path
required: true
schema:
$ref: '#/components/schemas/PostId'
style: simple
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/DeletePostsResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
get:
security:
- OAuth2UserToken:
- tweet.read
- users.read
- UserToken: []
- BearerToken: []
tags:
- Posts
summary: Get Posts by ID
operationId: getPostsById
parameters:
- name: id
in: path
required: true
schema:
$ref: '#/components/schemas/PostId'
style: simple
- $ref: '#/components/parameters/PostFieldsParameter'
- $ref: '#/components/parameters/PostExpansionsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/MediaFieldsParameter'
- $ref: '#/components/parameters/PollFieldsParameter'
- $ref: '#/components/parameters/PlaceFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/GetPostsByIdResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
servers:
- description: X API
url: https://api.x.com
/2/tweets/{id}/liking_users:
get:
security:
- OAuth2UserToken:
- like.read
- tweet.read
- users.read
- UserToken: []
tags:
- Posts
summary: Get Posts Liking Users
operationId: getPostsLikingUsers
parameters:
- name: id
in: path
required: true
schema:
$ref: '#/components/schemas/PostId'
style: simple
- name: max_results
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 100
style: form
- name: pagination_token
in: query
description: A base32hex-encoded pagination token.
required: false
schema:
type: string
minLength: 1
style: form
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/UserExpansionsParameter'
- $ref: '#/components/parameters/PostFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/GetPostsLikingUsersResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
servers:
- description: X API
url: https://api.x.com
/2/tweets/{id}/quote_tweets:
get:
security:
- OAuth2UserToken:
- users.read
- tweet.read
- UserToken: []
- BearerToken: []
tags:
- Posts
summary: Get Posts Quoted Posts
operationId: getPostsQuotedPosts
parameters:
- name: id
in: path
required: true
schema:
$ref: '#/components/schemas/PostId'
style: simple
- name: max_results
in: query
required: false
schema:
type: integer
minimum: 10
maximum: 100
format: int32
default: 10
style: form
- name: pagination_token
in: query
description: A base32hex-encoded pagination token.
required: false
schema:
type: string
minLength: 1
style: form
- name: exclude
in: query
required: false
schema:
type: array
minItems: 1
uniqueItems: true
items:
type: string
enum:
- replies
- retweets
explode: false
style: form
- $ref: '#/components/parameters/PostFieldsParameter'
- $ref: '#/components/parameters/PostExpansionsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/MediaFieldsParameter'
- $ref: '#/components/parameters/PollFieldsParameter'
- $ref: '#/components/parameters/PlaceFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/GetPostsQuotedPostsResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
servers:
- description: X API
url: https://api.x.com
/2/tweets/{id}/retweeted_by:
get:
security:
- OAuth2UserToken:
- tweet.read
- users.read
- UserToken: []
- BearerToken: []
tags:
- Posts
summary: Get Posts Reposted by
operationId: getPostsRepostedBy
parameters:
- name: id
in: path
required: true
schema:
$ref: '#/components/schemas/PostId'
style: simple
- name: max_results
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 100
style: form
- name: pagination_token
in: query
description: A base32hex-encoded pagination token.
required: false
schema:
type: string
minLength: 1
style: form
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/UserExpansionsParameter'
- $ref: '#/components/parameters/PostFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/GetPostsRepostedByResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
servers:
- description: X API
url: https://api.x.com
/2/tweets/{id}/retweets:
get:
security:
- OAuth2UserToken:
- users.read
- tweet.read
- UserToken: []
- BearerToken: []
tags:
- Posts
summary: Get Posts Reposts
operationId: getPostsReposts
parameters:
- name: id
in: path
required: true
schema:
$ref: '#/components/schemas/PostId'
style: simple
- name: max_results
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
format: int32
default: 100
style: form
- name: pagination_token
in: query
description: A base32hex-encoded pagination token.
required: false
schema:
type: string
minLength: 1
style: form
- $ref: '#/components/parameters/PostFieldsParameter'
- $ref: '#/components/parameters/PostExpansionsParameter'
- $ref: '#/components/parameters/UserFieldsParameter'
- $ref: '#/components/parameters/MediaFieldsParameter'
- $ref: '#/components/parameters/PollFieldsParameter'
- $ref: '#/components/parameters/PlaceFieldsParameter'
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/GetPostsRepostsResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
servers:
- description: X API
url: https://api.x.com
/2/tweets/{tweet_id}/hidden:
put:
security:
- OAuth2UserToken:
- users.read
- tweet.read
- tweet.moderate.write
- UserToken: []
tags:
- Posts
summary: Hide reply
description: Hides or unhides a reply to a conversation owned by the authenticated user.
externalDocs:
url: https://developer.twitter.com/en/docs/twitter-api/tweets/hide-replies/api-reference/put-tweets-id-hidden
operationId: hidePostsReply
parameters:
- name: tweet_id
in: path
required: true
schema:
$ref: '#/components/schemas/PostId'
style: simple
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/HidePostsReplyRequest'
required: true
responses:
'200':
description: The request has succeeded.
content:
application/json:
schema:
$ref: '#/components/schemas/HidePostsReplyResponse'
default:
description: The request has failed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
servers:
- description: X API
url: https://api.x.com
/tweets:
post:
tags:
- Posts
summary: Create a new post
operationId: createTweet
responses:
'201':
description: Created post
security:
- BearerAuth: []
servers:
- url: https://api.x.com/2
description: X API v2 production server
/tweets/search/all:
get:
tags:
- Posts
summary: Full-archive search of posts
operationId: searchAllTweets
parameters:
- name: query
in: query
required: true
schema:
type: string
description: Search query in X query language
responses:
'200':
description: Matching posts
security:
- BearerAuth: []
servers:
- url: https://api.x.com/2
description: X API v2 production server
/tweets/search/stream:
get:
tags:
- Posts
summary: Near real-time filtered stream of posts
operationId: getFilteredStream
responses:
'200':
description: Streamed posts matching the configured rules
security:
- BearerAuth: []
servers:
- url: https://api.x.com/2
description: X API v2 production server
/tweets/search/stream/rules:
post:
tags:
- Posts
summary: Add or delete rules for the filtered stream
operationId: updateFilteredStreamRules
responses:
'201':
description: Rules updated
security:
- BearerAuth: []
get:
tags:
- Posts
summary: List the active rules for the filtered stream
operationId: getFilteredStreamRules
responses:
'200':
description: Current filtered stream rules
security:
- BearerAuth: []
servers:
- url: https://api.x.com/2
description: X API v2 production server
components:
schemas:
CreatePostsResponseData:
type: object
required:
- id
- text
properties:
edit_history_post_ids:
type: array
description: Post IDs in this Post's edit history chain.
items:
type: string
id:
type: string
description: Unique identifier of the created Post.
pattern: ^[0-9]{1,19}$
text:
type: string
description: The content of the created Post.
AnalyticsTimestampedMetrics:
type: array
description: Time-bucketed engagement metrics for the Post, one entry per granularity bucket.
items:
type: object
properties:
metrics:
type:
- object
- 'null'
description: Engagement metric counts for this bucket.
properties:
app_install_attempts:
type:
- integer
- 'null'
format: int64
app_opens:
type:
- integer
- 'null'
format: int64
bookmarks:
type:
- integer
- 'null'
format: int64
detail_expands:
type:
- integer
- 'null'
format: int64
email_tweet:
type:
- integer
- 'null'
format: int64
engagements:
type:
- integer
- 'null'
format: int64
follows:
type:
- integer
- 'null'
format: int64
hashtag_clicks:
type:
- integer
- 'null'
format: int64
impressions:
type:
- integer
- 'null'
format: int64
likes:
type:
- integer
- 'null'
format: int64
media_views:
type:
- integer
- 'null'
format: int64
permalink_clicks:
type:
- integer
- 'null'
format: int64
quote_tweets:
type:
- integer
- 'null'
format: int64
replies:
type:
- integer
- 'null'
format: int64
retweets:
type:
- integer
- 'null'
format: int64
shares:
type:
- integer
- 'null'
format: int64
unfollows:
type:
- integer
- 'null'
format: int64
unlikes:
type:
- integer
- 'null'
format: int64
url_clicks:
type:
- integer
- 'null'
format: int64
user_profile_clicks:
type:
- integer
- 'null'
format: int64
timestamp:
type:
- string
- 'null'
description: Start of the metrics bucket, as an ISO 8601 date-time.
FieldHydrationFailureProblem:
type: object
required:
- type
- title
- detail
- field
properties:
detail:
type: string
field:
type: string
resource_type:
type: string
section:
type: string
status:
type: integer
title:
type: string
type:
type: string
enum:
- https://api.x.com/2/problems/field-hydration-failure
CreatePostsMediaCallToActionsVisitSite:
type: object
required:
- url
properties:
url:
type: string
desc
# --- truncated at 32 KB (106 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/x/refs/heads/main/openapi/x-posts-api-openapi.yml