Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: XPOZ Twitter (live) API
version: 1.0.0
description: 'Social media data API for Twitter/X, Instagram, Reddit, and TikTok.
**Data endpoints** (`/api/data/*`) are authenticated with an API access key and are metered against the account''s credits. Most stored-data endpoints share the same query options: `fields` selects which attributes to return, `since`/`until` bound the date range, and `responseType` picks between a synchronous first page (`fast`), a full paged query run as a background operation (`paging`), and a CSV export (`csv`). `/live` endpoints fetch from the platform on demand and page with a cursor instead.
**Account, billing, and crawl-settings endpoints** are used by the XPOZ dashboard and authenticate with the user''s session.'
servers:
- url: /
description: This server
tags:
- name: Twitter (live)
description: On-demand Twitter/X fetches straight from the platform, cursor-paginated. Not available for trial access keys.
paths:
/api/data/twitter/posts/live:
get:
tags:
- Twitter (live)
summary: Search tweets (live)
description: Search tweets on demand. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
security:
- AccessKey: []
parameters:
- $ref: '#/components/parameters/QueryQ'
- $ref: '#/components/parameters/Since'
- $ref: '#/components/parameters/Until'
- name: lang
in: query
required: false
description: BCP-47 language code filter.
schema:
type: string
- name: countryCode
in: query
required: false
description: ISO country code filter.
schema:
type: string
- name: sortBy
in: query
required: false
description: Sort order.
schema:
type: string
enum:
- relevance
- latest
- $ref: '#/components/parameters/TweetFields'
- $ref: '#/components/parameters/Cursor'
responses:
'200':
description: One page of results.
content:
application/json:
schema:
$ref: '#/components/schemas/CursorResponse'
'400':
description: Validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/TrialForbidden'
default:
$ref: '#/components/responses/DataRouteError'
operationId: getDataTwitterPostsLive
post:
tags:
- Twitter (live)
summary: Get tweets by ID (live)
description: Fetch up to 100 tweets by ID on demand in a single platform call, charged as one request. Tweets that are unavailable are listed in `notFound`. Not available for trial access keys.
security:
- AccessKey: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
ids:
type: array
minItems: 1
maxItems: 100
items:
type: string
pattern: ^\d+$
description: Tweet IDs as numeric strings. Duplicates are removed; at most 100 unique IDs.
example:
- '20'
- '1585341984679469056'
fields:
$ref: '#/components/parameters/TweetFields/schema'
description: Tweet fields to return, as a JSON array.
required:
- ids
responses:
'200':
description: The tweets that were found, plus the requested IDs that were not.
content:
application/json:
schema:
$ref: '#/components/schemas/LookupResponse'
'400':
description: Validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/TrialForbidden'
default:
$ref: '#/components/responses/DataRouteError'
operationId: postDataTwitterPostsLive
/api/data/twitter/posts/users/{username}/live:
get:
tags:
- Twitter (live)
summary: Get a user's tweets (live)
description: Fetch a user's recent tweets on demand. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
security:
- AccessKey: []
parameters:
- $ref: '#/components/parameters/Username'
- $ref: '#/components/parameters/Since'
- $ref: '#/components/parameters/Until'
- $ref: '#/components/parameters/TweetFields'
- $ref: '#/components/parameters/Cursor'
responses:
'200':
description: One page of results.
content:
application/json:
schema:
$ref: '#/components/schemas/CursorResponse'
'400':
description: Validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/TrialForbidden'
default:
$ref: '#/components/responses/DataRouteError'
operationId: getDataTwitterPostsUsersUsernameLive
/api/data/twitter/posts/{id}/live:
get:
tags:
- Twitter (live)
summary: Get a tweet (live)
description: Fetch a single tweet on demand. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
security:
- AccessKey: []
parameters:
- $ref: '#/components/parameters/TwitterPostId'
- $ref: '#/components/parameters/TweetFields'
responses:
'200':
description: One page of results.
content:
application/json:
schema:
$ref: '#/components/schemas/CursorResponse'
'400':
description: 'Validation failed. Also returned when the post ID is invalid: `Post ID must be a numeric string`.'
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/TrialForbidden'
default:
$ref: '#/components/responses/DataRouteError'
operationId: getDataTwitterPostsIdLive
/api/data/twitter/posts/{id}/comments/live:
get:
tags:
- Twitter (live)
summary: Get tweet replies (live)
description: Fetch replies to a tweet on demand. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
security:
- AccessKey: []
parameters:
- $ref: '#/components/parameters/TwitterPostId'
- $ref: '#/components/parameters/TweetFields'
- $ref: '#/components/parameters/Cursor'
responses:
'200':
description: One page of results.
content:
application/json:
schema:
$ref: '#/components/schemas/CursorResponse'
'400':
description: 'Validation failed. Also returned when the post ID is invalid: `Post ID must be a numeric string`.'
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/TrialForbidden'
default:
$ref: '#/components/responses/DataRouteError'
operationId: getDataTwitterPostsIdCommentsLive
/api/data/twitter/posts/{id}/quotes/live:
get:
tags:
- Twitter (live)
summary: Get tweet quotes (live)
description: Fetch quote tweets on demand. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
security:
- AccessKey: []
parameters:
- $ref: '#/components/parameters/TwitterPostId'
- $ref: '#/components/parameters/TweetFields'
- $ref: '#/components/parameters/Cursor'
responses:
'200':
description: One page of results.
content:
application/json:
schema:
$ref: '#/components/schemas/CursorResponse'
'400':
description: 'Validation failed. Also returned when the post ID is invalid: `Post ID must be a numeric string`.'
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/TrialForbidden'
default:
$ref: '#/components/responses/DataRouteError'
operationId: getDataTwitterPostsIdQuotesLive
/api/data/twitter/posts/{id}/interacting-users/live:
get:
tags:
- Twitter (live)
summary: Get tweet interacting users (live)
description: Fetch users who commented on, quoted, or retweeted a tweet, on demand. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
security:
- AccessKey: []
parameters:
- $ref: '#/components/parameters/TwitterPostId'
- $ref: '#/components/parameters/TwitterInteractionType'
- $ref: '#/components/parameters/TwitterUserFields'
- $ref: '#/components/parameters/Cursor'
responses:
'200':
description: One page of results.
content:
application/json:
schema:
$ref: '#/components/schemas/CursorResponse'
'400':
description: 'Validation failed. Also returned when the post ID is invalid: `Post ID must be a numeric string`.'
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/TrialForbidden'
default:
$ref: '#/components/responses/DataRouteError'
operationId: getDataTwitterPostsIdInteractingUsersLive
/api/data/twitter/users/live:
get:
tags:
- Twitter (live)
summary: Search Twitter users (live)
description: Search Twitter users on demand. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
security:
- AccessKey: []
parameters:
- $ref: '#/components/parameters/QueryQ'
- $ref: '#/components/parameters/TwitterUserFields'
- $ref: '#/components/parameters/Cursor'
responses:
'200':
description: One page of results.
content:
application/json:
schema:
$ref: '#/components/schemas/CursorResponse'
'400':
description: Validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/TrialForbidden'
default:
$ref: '#/components/responses/DataRouteError'
operationId: getDataTwitterUsersLive
post:
tags:
- Twitter (live)
summary: Get Twitter users by ID (live)
description: Fetch up to 100 Twitter user profiles by user ID on demand in a single platform call, charged as one request. Missing or suspended users are listed in `notFound`. Not available for trial access keys.
security:
- AccessKey: []
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
ids:
type: array
minItems: 1
maxItems: 100
items:
type: string
pattern: ^\d+$
description: User IDs as numeric strings. Duplicates are removed; at most 100 unique IDs.
example:
- '44196397'
- '783214'
fields:
$ref: '#/components/parameters/TwitterUserFields/schema'
description: User fields to return, as a JSON array.
required:
- ids
responses:
'200':
description: The users that were found, plus the requested IDs that were not.
content:
application/json:
schema:
$ref: '#/components/schemas/LookupResponse'
'400':
description: Validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/TrialForbidden'
default:
$ref: '#/components/responses/DataRouteError'
operationId: postDataTwitterUsersLive
/api/data/twitter/users/{username}/live:
get:
tags:
- Twitter (live)
summary: Get a Twitter user (live)
description: Fetch a Twitter user profile on demand. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
security:
- AccessKey: []
parameters:
- $ref: '#/components/parameters/Username'
- $ref: '#/components/parameters/TwitterUserFields'
responses:
'200':
description: One page of results.
content:
application/json:
schema:
$ref: '#/components/schemas/CursorResponse'
'400':
description: Validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/TrialForbidden'
default:
$ref: '#/components/responses/DataRouteError'
operationId: getDataTwitterUsersUsernameLive
/api/data/twitter/users/{username}/connections/live:
get:
tags:
- Twitter (live)
summary: Get Twitter user connections (live)
description: Fetch followers or following of a user on demand. Fetches directly from the platform and returns one page with a cursor. Not available for trial access keys.
security:
- AccessKey: []
parameters:
- $ref: '#/components/parameters/Username'
- $ref: '#/components/parameters/ConnectionType'
- $ref: '#/components/parameters/TwitterUserFields'
- $ref: '#/components/parameters/Cursor'
responses:
'200':
description: One page of results.
content:
application/json:
schema:
$ref: '#/components/schemas/CursorResponse'
'400':
description: Validation failed.
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleError'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/TrialForbidden'
default:
$ref: '#/components/responses/DataRouteError'
operationId: getDataTwitterUsersUsernameConnectionsLive
components:
parameters:
TwitterUserFields:
name: fields
in: query
required: false
description: 'Twitter user fields to return. Comma-separated. Allowed values: id, profileImageUrl, profileBannerUrl, profileInterstitialType, status, username, verifiedType, name, description, location, protected, verified, followersCount, followingCount, tweetCount, listedCount, likesCount, mediaCount, pinnedTweetId, source, nLang, nLangsFiltered, label, labelType, isVerified, modifiedAt, createdAt, verifiedSinceDatetime, accountBasedIn, locationAccurate, usernameChanges, lastUsernameChangeDatetime.'
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- id
- profileImageUrl
- profileBannerUrl
- profileInterstitialType
- status
- username
- verifiedType
- name
- description
- location
- protected
- verified
- followersCount
- followingCount
- tweetCount
- listedCount
- likesCount
- mediaCount
- pinnedTweetId
- source
- nLang
- nLangsFiltered
- label
- labelType
- isVerified
- modifiedAt
- createdAt
- verifiedSinceDatetime
- accountBasedIn
- locationAccurate
- usernameChanges
- lastUsernameChangeDatetime
Username:
name: username
in: path
required: true
description: Username (without `@`).
schema:
type: string
Until:
name: until
in: query
required: false
description: End date (inclusive), YYYY-MM-DD.
schema:
type: string
format: date
TwitterInteractionType:
name: interactionType
in: query
required: true
description: Kind of interaction to list users for.
schema:
type: string
enum:
- commenters
- quoters
- retweeters
TwitterPostId:
name: id
in: path
required: true
description: Tweet ID (numeric string).
schema:
type: string
pattern: ^\d+$
Since:
name: since
in: query
required: false
description: Start date (inclusive), YYYY-MM-DD.
schema:
type: string
format: date
QueryQ:
name: q
in: query
required: true
description: Search query (Lucene-style keyword syntax). Must not be blank.
schema:
type: string
Cursor:
name: cursor
in: query
required: false
description: Opaque cursor from `next_page_cursor` of the previous page.
schema:
type: string
ConnectionType:
name: connectionType
in: query
required: true
description: Which side of the follow graph to return.
schema:
type: string
enum:
- followers
- following
TweetFields:
name: fields
in: query
required: false
description: 'Tweet fields to return. Comma-separated. Allowed values: id, authorId, authorUsername, text, bookmarkCount, impressionCount, likeCount, lang, possiblySensitive, deleted, suspended, quoteCount, replyCount, retweetCount, isRetweet, hasBirdwatchNotes, birdwatchNotesId, birdwatchNotesText, birdwatchNotesUrl, status, conversationId, quotedTweetId, retweetedTweetId, replyToTweetId, replyToUserId, replyToUsername, originalTweetId, editedTweets, hashtags, mentions, mediaUrls, urls, grokGeneratedContent, source, placeName, placeCountry, placeCountryCode, placeBoundingBoxCoordinates, placeCentroid, createdAt, createdAtDate.'
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- id
- authorId
- authorUsername
- text
- bookmarkCount
- impressionCount
- likeCount
- lang
- possiblySensitive
- deleted
- suspended
- quoteCount
- replyCount
- retweetCount
- isRetweet
- hasBirdwatchNotes
- birdwatchNotesId
- birdwatchNotesText
- birdwatchNotesUrl
- status
- conversationId
- quotedTweetId
- retweetedTweetId
- replyToTweetId
- replyToUserId
- replyToUsername
- originalTweetId
- editedTweets
- hashtags
- mentions
- mediaUrls
- urls
- grokGeneratedContent
- source
- placeName
- placeCountry
- placeCountryCode
- placeBoundingBoxCoordinates
- placeCentroid
- createdAt
- createdAtDate
schemas:
DataRouteError:
type: object
properties:
success:
type: boolean
const: false
message:
type: string
description: Endpoint-specific label, e.g. `Failed to retrieve Twitter posts`.
error:
type: string
description: Detail. `An unexpected error occurred` for unhandled failures.
required:
- success
- message
- error
LookupResponse:
allOf:
- $ref: '#/components/schemas/CursorResponse'
- type: object
properties:
notFound:
type: array
items:
type: string
description: Requested IDs the platform returned nothing for.
required:
- notFound
description: 'Envelope for on-demand lookups by ID: the entities found (never paginated, so `has_more` is false and `next_page_cursor` is null) plus the IDs that were not found.'
DataSource:
type: string
enum:
- database
- api
- hybrid
description: Where the results came from.
SimpleError:
type: object
properties:
success:
type: boolean
const: false
message:
type: string
required:
- success
- message
CursorResponse:
type: object
properties:
results:
type: array
items:
type: object
additionalProperties: true
description: Entity shaped by the requested `fields`.
count:
type: integer
dataSource:
$ref: '#/components/schemas/DataSource'
has_more:
type: boolean
next_page_cursor:
anyOf:
- type: string
- type: 'null'
required:
- results
- count
- dataSource
- has_more
- next_page_cursor
description: 'Envelope for on-demand `/live` endpoints: one provider page plus a cursor.'
TrialForbidden:
type: object
properties:
success:
type: boolean
const: false
code:
type: string
enum:
- on_demand_not_available_in_trial
message:
type: string
required:
- success
- code
- message
responses:
TrialForbidden:
description: On-demand search is not available for trial access keys.
content:
application/json:
schema:
$ref: '#/components/schemas/TrialForbidden'
Unauthorized:
description: Missing or invalid credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/SimpleError'
DataRouteError:
description: The request could not be fulfilled. Status is 400 for an empty or invalid search query, 402 when CSV export is blocked by plan limits, 500 otherwise.
content:
application/json:
schema:
$ref: '#/components/schemas/DataRouteError'
securitySchemes:
AccessKey:
type: http
scheme: bearer
description: 'XPOZ API access key, created from the dashboard or `POST /api/tokens`. Send as `Authorization: Bearer <access key>`.'
UserSession:
type: http
scheme: bearer
bearerFormat: JWT
description: 'Descope session JWT of a logged-in dashboard user. Send as `Authorization: Bearer <session JWT>`.'