openapi: 3.2.0 info: title: Xquik Tweets API version: '1.0' description: Xquik is an independent third-party service. x-guidance: '## Common tasks **Find a tweet** - GET /x/tweets/{id}. Returns text, author, metrics, media, and creation time. Cost: $0.00015 per lookup. **Search tweets** - GET /x/tweets/search?q={query}&limit={n}. Supports X operators, structured filters, Tweet IDs, and status URLs. Omit mode for automatic coverage. Cost: $0.00015 per returned tweet. **Find a user** - GET /x/users/{id}. Accepts an ID or username. Cost: $0.00015 per lookup. **Check if A follows B** - GET /x/followers/check?source={a}&target={b}. Accepts usernames or profile URLs. Cost: $0.00075. **Get trends** - GET /trends?woeid={region}&count={n}. WOEID 1 is worldwide. Cost: $0.00045. **Download media** - POST /x/media/download with `tweetIds`. Fresh Tweets cost 1 credit each. Cached repeats are free. **Read an article** - GET /x/articles/{tweetId}. Cost: $0.00075. ## Pagination Default platform pages return `hasMore` and `nextCursor`. X pages return `has_next_page` and `next_cursor`. The 2026-04-29 contract returns `has_more` and `next_cursor`. Pass cursors through `cursor`; `after` remains compatible. Dynamic pricing counts returned items, not requests. Omit `mode` for automatic reads. Pass cursors unchanged. `mode=standard` remains legacy. Retry 409 responses after `Retry-After`. Restart 410 responses without a cursor. ## Authentication Eligible reads accept guest wallets. Fixed-price lookups also accept MPP. Other features require an API key or OAuth 2.1 bearer token. API keys also support `Authorization: Bearer xq_...`. ## Best-Practice Response Contract v1 remains the default. Send `xquik-api-contract: 2026-04-29` for snake_case, Unix timestamps, structured errors, unified pagination, resource objects, and prefixed IDs. Dependency failures use 424 instead of 502.' contact: name: Xquik url: https://xquik.com email: support@xquik.com servers: - url: https://xquik.com security: - apiKey: [] - oauthBearer: [] tags: - name: Tweets description: Look up, search, and analyze individual tweets paths: /api/v1/x/tweets: get: operationId: getBatchTweets summary: Get multiple tweets by IDs tags: - Tweets security: - apiKey: [] - oauthBearer: [] - {} parameters: - name: ids in: query required: true schema: type: string description: Comma-separated tweet IDs (max 100) responses: '200': description: Requested tweets in request order. Partial successful reads recheck unresolved IDs once. content: application/json: schema: $ref: '#/components/schemas/PaginatedTweets' example: tweets: - id: '1234567890' text: Just launched our new feature! createdAt: '2025-01-15T12:00:00Z' likeCount: 42 retweetCount: 5 replyCount: 3 quoteCount: 1 viewCount: 1500 bookmarkCount: 2 author: id: '9876543210' username: elonmusk name: Elon Musk verified: true has_next_page: false next_cursor: '' '400': $ref: '#/components/responses/InvalidInput' '401': $ref: '#/components/responses/AnonymousGuestAuthenticationRequired' '402': $ref: '#/components/responses/PaymentRequired' '424': $ref: '#/components/responses/XApiError' '429': $ref: '#/components/responses/RateLimitExceeded' '502': $ref: '#/components/responses/XApiError' default: $ref: '#/components/responses/UnexpectedError' description: Get multiple tweets by IDs. /api/v1/x/tweets/search: get: operationId: searchTweets summary: Search tweets by query, Tweet ID, X status URL, or account date window description: No-mode search maximizes coverage. New cursorless `Latest` sessions return rows newest-first across cursor pages. Existing cursors preserve their established ordering. tags: - Tweets security: - apiKey: [] - oauthBearer: [] - {} parameters: - name: q in: query required: true schema: type: string description: Query, Tweet ID, or status URL. Valid inline bounds apply per page. - name: queryType in: query required: false schema: type: string enum: - Latest - Top default: Latest description: Sort order - Latest (chronological) or Top (engagement-ranked) - $ref: '#/components/parameters/AutomaticCoverageMode' - $ref: '#/components/parameters/AutomaticCoverageCursor' - name: sinceTime in: query schema: type: string description: Inclusive ISO bound. - name: untilTime in: query schema: type: string description: Exclusive ISO bound. - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 10000 description: 'Result upper bound. Omit it for the existing 20-row page size. Explicit coverage defaults to 2000 and allows 10000. For paid requests, remaining credits can reduce results. Zero affordable results returns 402. ' - $ref: '#/components/parameters/TweetFilterFromUser' - $ref: '#/components/parameters/TweetFilterToUser' - $ref: '#/components/parameters/TweetFilterMentioning' - $ref: '#/components/parameters/TweetFilterLanguage' - $ref: '#/components/parameters/TweetFilterSinceDate' - $ref: '#/components/parameters/TweetFilterUntilDate' - $ref: '#/components/parameters/TweetFilterMediaType' - $ref: '#/components/parameters/TweetFilterMinFaves' - $ref: '#/components/parameters/TweetFilterMinRetweets' - $ref: '#/components/parameters/TweetFilterMinReplies' - $ref: '#/components/parameters/TweetFilterMinQuotes' - $ref: '#/components/parameters/TweetFilterMinViews' - $ref: '#/components/parameters/TweetFilterMinBookmarks' - $ref: '#/components/parameters/TweetFilterMaxFaves' - $ref: '#/components/parameters/TweetFilterMaxRetweets' - $ref: '#/components/parameters/TweetFilterMaxReplies' - $ref: '#/components/parameters/TweetFilterMaxQuotes' - $ref: '#/components/parameters/TweetFilterBlueVerifiedOnly' - $ref: '#/components/parameters/TweetFilterCardName' - $ref: '#/components/parameters/TweetFilterSource' - $ref: '#/components/parameters/TweetFilterExcludeSource' - $ref: '#/components/parameters/TweetFilterGeocode' - $ref: '#/components/parameters/TweetFilterSinceId' - $ref: '#/components/parameters/TweetFilterMaxId' - $ref: '#/components/parameters/TweetFilterNear' - $ref: '#/components/parameters/TweetFilterWithin' - $ref: '#/components/parameters/TweetFilterWithinTime' - $ref: '#/components/parameters/TweetFilterNativeRetweets' - $ref: '#/components/parameters/TweetFilterSafe' - $ref: '#/components/parameters/TweetFilterNews' - $ref: '#/components/parameters/TweetFilterVerifiedOnly' - $ref: '#/components/parameters/TweetFilterReplies' - $ref: '#/components/parameters/TweetFilterRetweets' - $ref: '#/components/parameters/TweetFilterQuotes' - $ref: '#/components/parameters/TweetFilterExactPhrase' - $ref: '#/components/parameters/TweetFilterExcludeWords' - $ref: '#/components/parameters/TweetFilterAnyWords' - $ref: '#/components/parameters/TweetFilterHashtags' - $ref: '#/components/parameters/TweetFilterCashtags' - $ref: '#/components/parameters/TweetFilterUrl' - $ref: '#/components/parameters/TweetFilterConversationId' - $ref: '#/components/parameters/TweetFilterInReplyToTweetId' - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId' - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId' - $ref: '#/components/parameters/TweetSearchListId' - $ref: '#/components/parameters/TweetSearchPlace' - $ref: '#/components/parameters/TweetSearchPlaceCountry' - $ref: '#/components/parameters/TweetSearchPointRadius' - $ref: '#/components/parameters/TweetSearchBoundingBox' - $ref: '#/components/parameters/TweetSearchAdvancedQuery' responses: '200': description: Search results content: application/json: schema: oneOf: - $ref: '#/components/schemas/PaginatedTweets' - $ref: '#/components/schemas/TweetSearchCoverageResponse' example: tweets: - id: '1234567890' text: Just launched our new feature! createdAt: '2025-01-15T12:00:00Z' likeCount: 42 retweetCount: 5 replyCount: 3 quoteCount: 1 viewCount: 1500 bookmarkCount: 2 author: id: '9876543210' username: elonmusk name: Elon Musk verified: true has_next_page: true next_cursor: DAACCgACGRElMJcAAA '400': description: Missing query content: application/json: schema: $ref: '#/components/schemas/Error' example: error: missing_query '401': $ref: '#/components/responses/AnonymousGuestAuthenticationRequired' '402': $ref: '#/components/responses/PaymentRequired' '409': $ref: '#/components/responses/CoverageCursorUnavailable' '410': $ref: '#/components/responses/CursorGone' '424': $ref: '#/components/responses/XApiError' '429': $ref: '#/components/responses/RateLimitExceeded' '502': $ref: '#/components/responses/XApiError' '503': $ref: '#/components/responses/MaximumCoverageBusy' default: $ref: '#/components/responses/UnexpectedError' /api/v1/x/tweets/{id}: get: operationId: lookupTweet summary: Get tweet with full text, author, metrics and media tags: - Tweets security: - apiKey: [] - oauthBearer: [] - {} x-payment-info: offers: - amount: '150' currency: '0x20c000000000000000000000b9537d11c60e8b50' intent: charge method: tempo parameters: - name: id in: path required: true schema: type: string description: Numeric tweet ID, 15-20 digits responses: '200': description: Tweet with author content: application/json: schema: type: object required: - tweet properties: tweet: $ref: '#/components/schemas/TweetDetail' author: $ref: '#/components/schemas/TweetAuthor' example: id: '9876543210' username: elonmusk name: Elon Musk followers: 150000000 verified: true example: tweet: id: '1234567890' text: Just launched our new feature! createdAt: '2025-01-15T12:00:00Z' retweetCount: 5 replyCount: 3 likeCount: 42 quoteCount: 1 viewCount: 1500 bookmarkCount: 2 author: id: '9876543210' username: elonmusk name: Elon Musk followers: 150000000 verified: true '400': $ref: '#/components/responses/InvalidInput' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '404': description: Tweet not found content: application/json: schema: $ref: '#/components/schemas/Error' example: error: tweet_not_found message: Tweet not found. Check the tweet ID. '424': $ref: '#/components/responses/XApiError' '429': $ref: '#/components/responses/RateLimitExceeded' '502': $ref: '#/components/responses/XApiError' default: $ref: '#/components/responses/UnexpectedError' description: Get tweet with full text, author, metrics and media. /api/v1/x/tweets/{id}/favoriters: get: operationId: getTweetFavoriters summary: List visible users who liked a tweet description: Returns liker profiles that X makes visible for the post. X can withhold liker identities even when the post reports likes. In that case this endpoint returns 424 `favoriters_unavailable` instead of a misleading empty success. tags: - Tweets security: - apiKey: [] - oauthBearer: [] - {} parameters: - name: id in: path required: true schema: type: string description: Tweet ID to get favoriters - name: cursor in: query schema: type: string description: Pagination cursor for favoriters - $ref: '#/components/parameters/FollowerPageSize' - $ref: '#/components/parameters/UserFilterMinFollowers' - $ref: '#/components/parameters/UserFilterMaxFollowers' - $ref: '#/components/parameters/UserFilterMinFollowing' - $ref: '#/components/parameters/UserFilterMaxFollowing' - $ref: '#/components/parameters/UserFilterMinStatuses' - $ref: '#/components/parameters/UserFilterMaxStatuses' - $ref: '#/components/parameters/UserFilterMinAccountAgeDays' - $ref: '#/components/parameters/UserFilterVerifiedOnly' - $ref: '#/components/parameters/UserFilterVerifiedType' - $ref: '#/components/parameters/UserFilterHasWebsite' - $ref: '#/components/parameters/UserFilterHasLocation' - $ref: '#/components/parameters/UserFilterBioContains' - $ref: '#/components/parameters/UserFilterLocationContains' - $ref: '#/components/parameters/UserFilterUsernameContains' responses: '200': description: Visible users who liked the tweet content: application/json: schema: $ref: '#/components/schemas/PaginatedUsers' '400': $ref: '#/components/responses/InvalidInput' '401': $ref: '#/components/responses/AnonymousGuestAuthenticationRequired' '402': $ref: '#/components/responses/PaymentRequired' '424': $ref: '#/components/responses/FavoritersUnavailable' '429': $ref: '#/components/responses/RateLimitExceeded' '502': $ref: '#/components/responses/XApiError' default: $ref: '#/components/responses/UnexpectedError' /api/v1/x/bookmarks: get: operationId: getBookmarks summary: Get bookmarked tweets tags: - Tweets security: - apiKey: [] - oauthBearer: [] parameters: - name: folderId in: query schema: type: string description: Optional bookmark folder ID - name: cursor in: query schema: type: string example: DAACCgACGRElMJcAAA description: Pagination cursor for bookmarks responses: '200': description: List of bookmarked tweets content: application/json: schema: $ref: '#/components/schemas/PaginatedTweets' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '424': $ref: '#/components/responses/XApiError' '429': $ref: '#/components/responses/RateLimitExceeded' '502': $ref: '#/components/responses/XApiError' default: $ref: '#/components/responses/UnexpectedError' description: Get bookmarked tweets. /api/v1/x/bookmarks/folders: get: operationId: getBookmarkFolders summary: Get bookmark folders tags: - Tweets security: - apiKey: [] - oauthBearer: [] responses: '200': description: List of bookmark folders content: application/json: schema: type: object required: - folders - has_next_page - next_cursor properties: folders: type: array items: type: object required: - id - name properties: id: type: string example: '1234567890' name: type: string example: Read Later example: - id: '1234567890' name: Read Later has_next_page: type: boolean description: Always false for the current bookmark folder route example: false next_cursor: type: string description: Always empty for the current bookmark folder route example: '' example: folders: - id: '1234567890' name: Read Later has_next_page: false next_cursor: '' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '424': $ref: '#/components/responses/XApiError' '429': $ref: '#/components/responses/RateLimitExceeded' '502': $ref: '#/components/responses/XApiError' default: $ref: '#/components/responses/UnexpectedError' description: Get bookmark folders. /api/v1/x/timeline: get: operationId: getTimeline summary: Get home timeline tags: - Tweets security: - apiKey: [] - oauthBearer: [] parameters: - name: seenTweetIds in: query schema: type: string description: Comma-separated tweet IDs to exclude from results. Empty entries are ignored. - name: cursor in: query schema: type: string description: Pagination cursor for timeline responses: '200': description: List of timeline tweets content: application/json: schema: $ref: '#/components/schemas/PaginatedTweets' '401': $ref: '#/components/responses/Unauthenticated' '402': $ref: '#/components/responses/PaymentRequired' '424': $ref: '#/components/responses/XApiError' '429': $ref: '#/components/responses/RateLimitExceeded' '502': $ref: '#/components/responses/XApiError' default: $ref: '#/components/responses/UnexpectedError' description: Get home timeline. /api/v1/x/tweets/{id}/quotes: get: operationId: getTweetQuotes summary: List quote tweets of a tweet tags: - Tweets security: - apiKey: [] - oauthBearer: [] - {} parameters: - name: id in: path required: true schema: type: string description: Numeric tweet ID to get quotes, 15-20 digits - $ref: '#/components/parameters/AutomaticCoverageCursor' - name: mode in: query schema: type: string enum: - standard description: Optional legacy pagination override. - $ref: '#/components/parameters/AutomaticTweetPageSize' - name: sinceTime in: query schema: type: string description: Unix timestamp - return quotes posted after this time - name: untilTime in: query schema: type: string description: Unix timestamp - return quotes posted before this time - name: includeReplies in: query schema: type: boolean description: Include reply quotes (default false) - $ref: '#/components/parameters/TweetFilterFromUser' - $ref: '#/components/parameters/TweetFilterToUser' - $ref: '#/components/parameters/TweetFilterMentioning' - $ref: '#/components/parameters/TweetFilterLanguage' - $ref: '#/components/parameters/TweetFilterSinceDate' - $ref: '#/components/parameters/TweetFilterUntilDate' - $ref: '#/components/parameters/TweetFilterMediaType' - $ref: '#/components/parameters/TweetFilterMinFaves' - $ref: '#/components/parameters/TweetFilterMinRetweets' - $ref: '#/components/parameters/TweetFilterMinReplies' - $ref: '#/components/parameters/TweetFilterMinQuotes' - $ref: '#/components/parameters/TweetFilterMinViews' - $ref: '#/components/parameters/TweetFilterMinBookmarks' - $ref: '#/components/parameters/TweetFilterMaxFaves' - $ref: '#/components/parameters/TweetFilterMaxRetweets' - $ref: '#/components/parameters/TweetFilterMaxReplies' - $ref: '#/components/parameters/TweetFilterMaxQuotes' - $ref: '#/components/parameters/TweetFilterBlueVerifiedOnly' - $ref: '#/components/parameters/TweetFilterCardName' - $ref: '#/components/parameters/TweetFilterSource' - $ref: '#/components/parameters/TweetFilterExcludeSource' - $ref: '#/components/parameters/TweetFilterGeocode' - $ref: '#/components/parameters/TweetFilterSinceId' - $ref: '#/components/parameters/TweetFilterMaxId' - $ref: '#/components/parameters/TweetFilterNear' - $ref: '#/components/parameters/TweetFilterWithin' - $ref: '#/components/parameters/TweetFilterWithinTime' - $ref: '#/components/parameters/TweetFilterNativeRetweets' - $ref: '#/components/parameters/TweetFilterSafe' - $ref: '#/components/parameters/TweetFilterNews' - $ref: '#/components/parameters/TweetFilterVerifiedOnly' - $ref: '#/components/parameters/TweetFilterReplies' - $ref: '#/components/parameters/TweetFilterRetweets' - $ref: '#/components/parameters/TweetFilterQuotes' - $ref: '#/components/parameters/TweetFilterExactPhrase' - $ref: '#/components/parameters/TweetFilterExcludeWords' - $ref: '#/components/parameters/TweetFilterAnyWords' - $ref: '#/components/parameters/TweetFilterHashtags' - $ref: '#/components/parameters/TweetFilterCashtags' - $ref: '#/components/parameters/TweetFilterUrl' - $ref: '#/components/parameters/TweetFilterConversationId' - $ref: '#/components/parameters/TweetFilterInReplyToTweetId' - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId' - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId' responses: '200': description: List of quote tweets content: application/json: schema: $ref: '#/components/schemas/PaginatedTweets' '400': $ref: '#/components/responses/InvalidInput' '401': $ref: '#/components/responses/AnonymousGuestAuthenticationRequired' '402': $ref: '#/components/responses/PaymentRequired' '424': $ref: '#/components/responses/XApiError' '429': $ref: '#/components/responses/RateLimitExceeded' '502': $ref: '#/components/responses/XApiError' default: $ref: '#/components/responses/UnexpectedError' description: List quote tweets of a tweet. /api/v1/x/tweets/{id}/replies: get: operationId: getTweetReplies summary: List replies to a tweet description: Returns direct replies. Omit mode for automatic maximum coverage with resumable pagination. Complete mode returns nested replies, diagnostics, and 424 when direct coverage stays below 80%. tags: - Tweets security: - apiKey: [] - oauthBearer: [] - {} parameters: - name: id in: path required: true schema: type: string description: Tweet ID to get replies - $ref: '#/components/parameters/AutomaticCoverageCursor' - name: mode in: query schema: type: string enum: - standard - complete description: 'Optional advanced override. Omit mode for automatic maximum direct reply coverage with pagination. Standard keeps legacy pagination. Complete returns direct and nested replies with diagnostics, scope, depth, sorting, and original-post controls. ' - name: limit in: query schema: type: integer minimum: 1 maximum: 25000 description: 'With mode=complete, maximum combined direct and nested reply rows (1-25000, default 25000). Automatic pages accept 1-300. Standard pages accept 1-100. Prefer pageSize outside complete mode. ' - $ref: '#/components/parameters/AutomaticTweetPageSize' - name: scope in: query schema: type: string enum: - all - direct - nested default: all description: Select all replies, direct replies, or nested replies. - name: maxDepth in: query schema: type: integer minimum: 1 description: Maximum reply depth from the source post. - name: sort in: query schema: type: string enum: - relevance - latest - oldest - likes default: relevance description: Sort the selected replies before applying limit. - name: excludeOriginalAuthor in: query schema: type: boolean default: false description: Exclude replies written by the source-post author. - name: includeOriginalPost in: query schema: type: boolean default: false description: Include the source post and count it toward limit. - name: hasMediaOnly in: query schema: type: boolean default: false description: Only return replies containing media. - name: sinceTime in: query schema: type: string description: Unix timestamp - return replies posted after this time - name: untilTime in: query schema: type: string description: Unix timestamp - return replies posted before this time - $ref: '#/components/parameters/TweetFilterFromUser' - $ref: '#/components/parameters/TweetFilterToUser' - $ref: '#/components/parameters/TweetFilterMentioning' - $ref: '#/components/parameters/TweetFilterLanguage' - $ref: '#/components/parameters/TweetFilterSinceDate' - $ref: '#/components/parameters/TweetFilterUntilDate' - $ref: '#/components/parameters/TweetFilterMediaType' - $ref: '#/components/parameters/TweetFilterMinFaves' - $ref: '#/components/parameters/TweetFilterMinRetweets' - $ref: '#/components/parameters/TweetFilterMinReplies' - $ref: '#/components/parameters/TweetFilterMinQuotes' - $ref: '#/components/parameters/TweetFilterMinViews' - $ref: '#/components/parameters/TweetFilterMinBookmarks' - $ref: '#/components/parameters/TweetFilterMaxFaves' - $ref: '#/components/parameters/TweetFilterMaxRetweets' - $ref: '#/components/parameters/TweetFilterMaxReplies' - $ref: '#/components/parameters/TweetFilterMaxQuotes' - $ref: '#/components/parameters/TweetFilterBlueVerifiedOnly' - $ref: '#/components/parameters/TweetFilterCardName' - $ref: '#/components/parameters/TweetFilterSource' - $ref: '#/components/parameters/TweetFilterExcludeSource' - $ref: '#/components/parameters/TweetFilterGeocode' - $ref: '#/components/parameters/TweetFilterSinceId' - $ref: '#/components/parameters/TweetFilterMaxId' - $ref: '#/components/parameters/TweetFilterNear' - $ref: '#/components/parameters/TweetFilterWithin' - $ref: '#/components/parameters/TweetFilterWithinTime' - $ref: '#/components/parameters/TweetFilterNativeRetweets' - $ref: '#/components/parameters/TweetFilterSafe' - $ref: '#/components/parameters/TweetFilterNews' - $ref: '#/components/parameters/TweetFilterVerifiedOnly' - $ref: '#/components/parameters/TweetFilterReplies' - $ref: '#/components/parameters/TweetFilterRetweets' - $ref: '#/components/parameters/TweetFilterQuotes' - $ref: '#/components/parameters/TweetFilterExactPhrase' - $ref: '#/components/parameters/TweetFilterExcludeWords' - $ref: '#/components/parameters/TweetFilterAnyWords' - $ref: '#/components/parameters/TweetFilterHashtags' - $ref: '#/components/parameters/TweetFilterCashtags' - $ref: '#/components/parameters/TweetFilterUrl' - $ref: '#/components/parameters/TweetFilterConversationId' - $ref: '#/components/parameters/TweetFilterInReplyToTweetId' - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId' - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId' responses: '200': description: List of replies content: application/json: schema: $ref: '#/components/schemas/TweetReplies' '400': $ref: '#/components/responses/InvalidInput' '401': $ref: '#/components/responses/AnonymousGuestAuthenticationRequired' '402': $ref: '#/components/responses/PaymentRequired' '409': $ref: '#/components/responses/CoverageCursorUnavailable' '410': $ref: '#/components/responses/CursorGone' '424': $ref: '#/components/responses/RepliesIncomplete' '429': $ref: '#/components/responses/RateLimitExceeded' '502': $ref: '#/components/responses/XApiError' '503': $ref: '#/components/responses/MaximumCoverageBusy' default: $ref: '#/components/responses/UnexpectedError' /api/v1/x/tweets/{id}/retweeters: get: operationId: getTweetRetweeters summary: List users who retweeted a tweet tags: - Tweets security: - apiKey: [] - oauthBearer: [] - {} parameters: - name: id in: path required: true schema: type: string description: Tweet ID to get retweeters - name: cursor in: query schema: type: string description: Pagination cursor for retweeters - $ref: '#/components/parameters/FollowerPageSize' - $ref: '#/components/parameters/UserFilterMinFollowers' - $ref: '#/components/parameters/UserFilterMaxFollowers' - $ref: '#/components/parameters/UserFilterMinFollowing' - $ref: '#/components/parameters/UserFilterMaxFollowing' - $ref: '#/components/parameters/UserFilterMinStatuses' - $ref: '#/components/parameters/UserFilterMaxStatuses' - $ref: '#/components/parameters/UserFilterMinAccountAgeDays' - $ref: '#/components/parameters/UserFilterVerifiedOnly' - $ref: '#/components/parameters/UserFilterVerifiedType' - $ref: '#/components/parameters/UserFilterHasWebsite' - $ref: '#/components/parameters/UserFilterHasLocation' - $ref: '#/components/parameters/UserFilterBioContains' - $ref: '#/components/parameters/UserFilterLocationContains' - $ref: '#/components/parameters/UserFilterUsernameContains' responses: '200': description: List of retweeters content: application/json: schema: $ref: '#/components/schemas/PaginatedUsers' '400': $ref: '#/components/responses/InvalidInput' '401': $ref: '#/components/responses/AnonymousGuestAuthenticationRequired' '402': $ref: '#/components/responses/PaymentRequired' '424': $ref: '#/components/responses/XApiError' '429': $ref: '#/components/responses/RateLimitExceeded' '502': $ref: '#/components/responses/XApiError' default: $ref: '#/components/responses/UnexpectedError' description: List users who retweeted a tweet. /api/v1/x/tweets/{id}/thread: get: operationId: getTweetThread summary: Get full conversation thread for a tweet tags: - Tweets security: - apiKey: [] - oauthBearer: [] - {} parameters: - name: id in: path required: true schema: type: string description: Tweet ID to get thread context - name: cursor in: query schema: type: string description: Pagination cursor for thread tweets - $ref: '#/components/parameters/ResultPageSize' - $ref: '#/components/parameters/TweetFilterFromUser' - $ref: '#/components/parameters/TweetFilterToUser' - $ref: '#/components/parameters/TweetFilterMentioning' - $ref: '#/components/parameters/TweetFilterLanguage' - $ref: '#/components/parameters/TweetFilterSinceDate' - $ref: '#/components/parameters/TweetFilterUntilDate' - $ref: '#/components/parameters/TweetFilterMediaType' - $ref: '#/components/parameters/TweetFilterMinFaves' - $ref: '#/components/parameters/TweetFilterMinRetweets' - $ref: '#/components/parameters/TweetFilterMinReplies' - $ref: '#/components/parameters/TweetFilterMinQuotes' - $ref: '#/components/parameters/TweetFilterMinViews' - $ref: '#/components/parameters/TweetFilterMinBookmarks' - $ref: '#/components/parameters/TweetFilterMaxFaves' - $ref: '#/components/parameters/TweetFilterMaxRetweets' - $ref: '#/components/parameters/TweetFilterMaxReplies' - $ref: '#/components/parameters/TweetFilterMaxQuotes' - $ref: '#/components/parameters/TweetFilterBlueVerifiedOnly' - $ref: '#/components/parameters/TweetFilterVerifiedOnly' - $ref: '#/components/parameters/TweetFilterReplies' - $ref: '#/components/parameters/TweetFilterRetweets' - $ref: '#/components/parameters/TweetFilterQuotes' - $ref: '#/components/parameters/TweetFilterExactPhrase' - $ref: '#/components/parameters/TweetFilterExcludeWords' - $ref: '#/components/parameters/TweetFilterAnyWords' - $ref: '#/components/parameters/TweetFilterHashtags' - $ref: '#/components/parameters/TweetFilterCashtags' - $ref: '#/components/parameters/TweetFilterUrl' - $ref: '#/components/parameters/TweetFilterConversationId' - $ref: '#/components/parameters/TweetFilterInReplyToTweetId' - $ref: '#/components/parameters/TweetFilterQuotesOfTweetId' - $ref: '#/components/parameters/TweetFilterRetweetsOfTweetId' responses: '200': description: Thread tweets content: application/json: schema: $ref: '#/components/schemas/PaginatedTweets' '400': $ref: '#/components/responses/InvalidInput' '401': $ref: '#/components/responses/AnonymousGuestAuthenticationRequired' '402': $ref: '#/components/responses/PaymentRequired' '424': $ref: '#/components/responses/XApiError' '429': $ref: '#/components/responses/RateLimitExceeded' '502': $ref: '#/components/responses/XApiError' default: $ref: '#/components/responses/UnexpectedError' description: Get full conversation thread for a tweet. components: schemas: TweetSearchCoverageWindow: description: Non-overlapping time partition used by one strategy. type: object required: - sinceTime - untilTime properties: sinceTime: type: string format: date-time untilTime: type: string format: date-time SearchTweet: description: Tweet returned from search results with inline author info. A zero metric can mean X did not report the count. type: object required: - id - text - retweetCount - replyCount - likeCount - quoteCount - viewCount - bookmarkCount properties: id: type: string text: type: string type: type: string createdAt: type: string isNoteTweet: type: boolean description: True for Note Tweets (long-form content, up to 25,000 characters) isReply: type: boolean description: True when this search result is a reply isQuoteStatus: type: boolean description: True when this search result quotes another tweet isLimitedReply: type: boolean description: Whether the tweet has limited reply permissions inReplyToId: type: string description: ID of the tweet this result replies to. inReplyToUserId: type: string description: ID of the user this result replies to. inReplyToUsername: type: string description: Username this result replies to. conversationId: type: string description: Root tweet ID for the search result conversation source: type: string description: Client application used to post the tweet displayTextRange: type: array items: type: integer description: Rendered text's start and end offsets. contentDisclosure: $ref: '#/components/schemas/ContentDisclosure' article: $ref: '#/components/schemas/TweetArticleMetadata' card: $ref: '#/components/schemas/TweetCard' communityNote: $ref: '#/components/schemas/TweetCommunityNote' edit: $ref: '#/components/schemas/TweetEdit' isTranslatable: type: boolean noteTweet: $ref: '#/components/schemas/TweetNote' place: $ref: '#/components/schemas/TweetPlace' possiblySensitive: type: boolean previousCounts: $ref: '#/components/schemas/TweetPreviousCounts' viewState: type: string entities: type: object additionalProperties: true description: Parsed search-result entities including URLs, mentions, hashtags, and media markers quoted_tweet: $ref: '#/components/schemas/EmbeddedTweet' retweeted_tweet: $ref: '#/components/schemas/EmbeddedTweet' media: type: array items: $ref: '#/components/schemas/TweetMedia' description: Search-result media attachments, omitted when no media is present url: type: string description: Search result permalink. lang: type: string description: Search result language code. likeCount: type: integer retweetCount: type: integer replyCount: type: integer quoteCount: type: integer viewCount: type: integer bookmarkCount: type: integer author: $ref: '#/components/schemas/UserProfile' TweetSearchCoverageDiagnostic: description: Coverage evidence across parallel search strategies. type: object required: - complete - cursorFailureCount - deadlineReached - duplicateCount - failedStrategyCount - malformedCount - pagesFetched - partitioned - responseTruncated - resultLimitReached - returnedTweets - stalledStrategyCount - strategies - strategyCount - uniqueTweets properties: complete: type: boolean description: True when every strategy exhausted its source. cursorFailureCount: type: integer minimum: 0 deadlineReached: type: boolean duplicateCount: type: integer minimum: 0 failedStrategyCount: type: integer minimum: 0 malformedCount: type: integer minimum: 0 pagesFetched: type: integer minimum: 0 partitioned: type: boolean description: Whether bounded time windows ran in parallel. responseTruncated: type: boolean description: Whether credits or the requested limit reduced output. resultLimitReached: type: boolean returnedTweets: type: integer minimum: 0 maximum: 10000 stalledStrategyCount: type: integer minimum: 0 strategies: type: array items: $ref: '#/components/schemas/TweetSearchCoverageStrategy' strategyCount: type: integer minimum: 1 maximum: 8 uniqueTweets: type: integer minimum: 0 maximum: 10000 MppPaymentRequired: description: Anonymous payment requirement for a direct MPP operation. The response includes an MPP challenge and an accountless checkout action. type: object required: - account_required - detail - next_step - payment_options - status - title - type properties: account_required: type: boolean const: false challengeId: type: string description: Opaque identifier for the MPP payment challenge. detail: type: string hint: type: string description: Instructions for selecting and paying an MPP offer. next_step: type: string const: Ask the user to confirm a USD amount before creating checkout. payment_options: type: object additionalProperties: false required: - guest_wallet properties: guest_wallet: type: object additionalProperties: false required: - create_checkout properties: create_checkout: $ref: '#/components/schemas/GuestWalletCreateCheckoutAction' status: type: integer const: 402 title: type: string const: Payment Required type: type: string format: uri const: https://paymentauth.org/problems/payment-required AuthenticatedPaymentRequired: description: Authenticated credit or subscription error with confirmation-gated hosted checkout actions. type: object additionalProperties: false required: - balance - dashboard - error - message - next_step - payment_options - required - top_up_endpoint - top_up_url properties: balance: type: string pattern: ^\d+$ description: Available credits as a decimal string. dashboard: type: string const: /dashboard/account description: Account page for manual billing management. error: type: string enum: - insufficient_credits - no_credits - no_subscription - subscription_inactive message: type: string next_step: type: string const: Ask the user to confirm a payment option before creating checkout. payment_options: type: object additionalProperties: false required: - credits - subscription properties: credits: type: object additionalProperties: false required: - create_checkout properties: create_checkout: type: object additionalProperties: false required: - body - creates - method - path - provider - requires_authentication - requires_user_confirmation - response_url_field properties: body: type: object additionalProperties: false required: - dollars - locale properties: dollars: type: integer const: 10 locale: type: string const: en creates: type: string const: checkout_url method: type: string const: POST path: type: string const: /api/v1/credits/topup provider: type: string deprecated: true const: stripe requires_authentication: type: boolean const: true requires_user_confirmation: type: boolean const: true response_url_field: type: string const: url subscription: type: object additionalProperties: false required: - create_checkout properties: create_checkout: type: object additionalProperties: false required: - body - creates - method - path - provider - requires_authentication - requires_user_confirmation - response_url_field properties: body: type: object additionalProperties: false required: - tier properties: tier: type: string const: starter creates: type: string const: checkout_url method: type: string const: POST path: type: string const: /api/v1/subscribe provider: type: string deprecated: true const: stripe requires_authentication: type: boolean const: true requires_user_confirmation: type: boolean const: true response_url_field: type: string const: url required: type: string pattern: ^\d+$ description: Credits required for the blocked request. top_up_endpoint: type: string const: /api/v1/credits/topup top_up_url: type: string const: POST /api/v1/credits/topup TweetAuthor: description: Tweet author profile. The lookup route always includes follower count and verification state. Other profile fields appear when available. allOf: - $ref: '#/components/schemas/UserProfile' - title: TweetAuthorRequirements type: object required: - followers - verified properties: followers: type: integer minimum: 0 verified: type: boolean XWriteActionNextAction: type: - object - 'null' description: Exact follow-up an API client or agent should perform. additionalProperties: false required: - type properties: type: type: string enum: - poll - retry - verify_result - fix_request url: type: string afterMs: type: integer minimum: 0 requiresNewIdempotencyKey: type: boolean TweetSearchCoverageStrategy: type: object required: - duplicateCount - pagesFetched - queryType - stopReason - strategy - uniqueAdded properties: duplicateCount: type: integer minimum: 0 pagesFetched: type: integer minimum: 0 queryType: type: string enum: - Latest - Top stopReason: $ref: '#/components/schemas/CoverageStopReason' strategy: type: integer minimum: 1 maximum: 8 uniqueAdded: type: integer minimum: 0 window: $ref: '#/components/schemas/TweetSearchCoverageWindow' XWritePaymentRequired: allOf: - $ref: '#/components/schemas/XWriteAction' - type: object required: - error - message description: 'Durable failed write action with the applicable payment guidance. ' GuestWalletTopupCheckoutAction: description: Explicit direct REST action for a guest wallet top-up. type: object additionalProperties: false required: - account_required - amount_bounds - body - creates - method - path - provider - required_headers - requires_authentication - requires_user_confirmation - requires_user_interaction - response_fields - response_url_field properties: account_required: type: boolean const: false amount_bounds: $ref: '#/components/schemas/GuestWalletAmountBounds' body: $ref: '#/components/schemas/GuestWalletPurchaseRequest' creates: type: string const: checkout_url method: type: string const: POST path: type: string const: /api/v1/guest-wallets/topups provider: type: string deprecated: true const: stripe required_headers: type: object additionalProperties: false required: - Idempotency-Key properties: Idempotency-Key: type: string const: requires_authentication: type: boolean const: true requires_user_confirmation: type: boolean const: true requires_user_interaction: type: boolean const: true response_fields: type: array minItems: 2 maxItems: 2 prefixItems: - type: string const: checkout_url - type: string const: status_url items: type: string enum: - checkout_url - status_url response_url_field: type: string const: checkout_url ReplyCoverageDiagnostic: description: Evidence for direct-reply coverage and collector behavior. type: object required: - complete - reportedReplyCount - targetDirectReplies - uniqueDirectReplies - coveragePercentage - nestedReplyCount - pagesAttempted - strategiesAttempted - duplicateCount - cursorFailures - repeatedCursorCount - emptyFalseProgressPages - malformedCount - unrelatedCount - missingResponseModulesOrFields - recommendedFallback - richness - responseTruncated properties: complete: type: boolean description: Whether coverage met the target without truncation. reportedReplyCount: type: integer minimum: 0 description: Reply count reported on the source post. targetDirectReplies: type: integer minimum: 0 description: Minimum direct replies required for the coverage target. uniqueDirectReplies: type: integer minimum: 0 description: Unique replies whose parent ID equals the source post ID. coveragePercentage: type: number minimum: 0 maximum: 100 description: Unique direct replies as a percentage of the reported count. nestedReplyCount: type: integer minimum: 0 description: Unique nested replies kept outside direct coverage. pagesAttempted: type: integer minimum: 0 description: Total pages attempted across all strategies. strategiesAttempted: type: array description: Per-strategy pagination and contribution evidence. items: $ref: '#/components/schemas/ReplyCoverageStrategy' duplicateCount: type: integer minimum: 0 description: Duplicate tweet IDs removed across pages and strategies. cursorFailures: type: integer minimum: 0 description: Cursor requests that failed. repeatedCursorCount: type: integer minimum: 0 description: Repeated cursors rejected to prevent loops. emptyFalseProgressPages: type: integer minimum: 0 description: Empty pages rejected because they did not make progress. malformedCount: type: integer minimum: 0 description: Malformed response items rejected. unrelatedCount: type: integer minimum: 0 description: Tweets rejected because they belonged elsewhere. missingResponseModulesOrFields: type: array description: Expected response modules or fields missing from X. items: type: string recommendedFallback: type: string description: Recommended next action when coverage is incomplete. richness: $ref: '#/components/schemas/ReplyCoverageRichness' responseTruncated: type: boolean description: Whether the requested row limit truncated safe results. Error: description: 'Error response. Default v1 returns a legacy string error code. Send `xquik-api-contract: 2026-04-29` to receive the structured best-practice error object. ' type: object required: - error properties: error: x-stainless-naming: python: type_name: ErrorValue java: type_name: ErrorValue oneOf: - type: string title: LegacyErrorCode enum: - internal_error - account_already_connected - account_needs_reauth - account_not_found - account_required - account_restricted - api_key_limit_reached - article_not_found - closed - dm_not_permitted - invalid_format - invalid_id - invalid_input - invalid_params - invalid_tool_type - invalid_tweet_id - invalid_tweet_url - invalid_user_id - invalid_user_ids - invalid_username - invalid_json - insufficient_credits - login_cooldown - login_failed - media_download_failed - missing_params - missing_query - monitor_already_exists - monitor_profile_unavailable - no_media - no_credits - no_subscription - not_found - payment_failed - rate_limit_exceeded - service_unavailable - style_not_found - subscription_inactive - tweet_not_found - unauthenticated - unsupported_field - user_not_found - body_too_large - checkout_unavailable - connection_challenge_expired - connection_challenge_inactive - coverage_cursor_gone - coverage_cursor_unavailable - draft_not_found - expired - favoriters_unavailable - forbidden - guest_wallet_unavailable - guest_wallets_disabled - guest_wallets_unavailable - idempotency_conflict - idempotency_key_conflict - invalid_community_id - invalid_complete_replies_request - invalid_coverage_cursor - invalid_coverage_request - invalid_idempotency_key - invalid_list_id - invalid_output_options - invalid_payment_amount - invalid_range - invalid_reply_options - login_rate_limited - login_service_unavailable - missing_idempotency_key - missing_ids - missing_url - no_cached_style - passkey_required - rate_limited - read_request_timeout - replies_incomplete - support_media_rate_limit - support_request_rate_limit - too_many_ids - too_many_tweets - unknown_field - unsupported_media_type - webhook_inactive - write_tracking_unavailable - x_write_unconfirmed - x_account_feature_required - x_account_protected - x_account_suspended - x_api_rate_limited - x_api_unavailable - x_api_unauthorized - x_auth_failure - x_content_too_long - x_daily_limit - x_dm_not_allowed - x_duplicate_action - x_login_auth_failed - x_login_challenge - x_login_denied - x_login_failed - x_login_proxy_error - x_login_rate_limited - x_login_service_unavailable - x_login_suspended - x_rate_limited - x_rejected - x_target_not_found - x_transient_error - x_user_lookup_failed - x_write_ambiguous - x_write_failed - type: object title: StructuredError required: - message - type - code properties: message: type: string type: type: string enum: - api_error - authentication_error - billing_error - dependency_error - invalid_request_error - permission_error - rate_limit_error code: type: string title: ErrorCode enum: - internal_error - account_already_connected - account_needs_reauth - account_not_found - account_required - account_restricted - api_key_limit_reached - article_not_found - closed - dm_not_permitted - invalid_format - invalid_id - invalid_input - invalid_params - invalid_tool_type - invalid_tweet_id - invalid_tweet_url - invalid_user_id - invalid_user_ids - invalid_username - invalid_json - insufficient_credits - login_cooldown - login_failed - media_download_failed - missing_params - missing_query - monitor_already_exists - monitor_profile_unavailable - no_media - no_credits - no_subscription - not_found - payment_failed - rate_limit_exceeded - service_unavailable - style_not_found - subscription_inactive - tweet_not_found - unauthenticated - unsupported_field - user_not_found - body_too_large - checkout_unavailable - connection_challenge_expired - connection_challenge_inactive - coverage_cursor_gone - coverage_cursor_unavailable - draft_not_found - expired - favoriters_unavailable - forbidden - guest_wallet_unavailable - guest_wallets_disabled - guest_wallets_unavailable - idempotency_conflict - idempotency_key_conflict - invalid_community_id - invalid_complete_replies_request - invalid_coverage_cursor - invalid_coverage_request - invalid_idempotency_key - invalid_list_id - invalid_output_options - invalid_payment_amount - invalid_range - invalid_reply_options - login_rate_limited - login_service_unavailable - missing_idempotency_key - missing_ids - missing_url - no_cached_style - passkey_required - rate_limited - read_request_timeout - replies_incomplete - support_media_rate_limit - support_request_rate_limit - too_many_ids - too_many_tweets - unknown_field - unsupported_media_type - webhook_inactive - write_tracking_unavailable - x_write_unconfirmed - x_account_feature_required - x_account_protected - x_account_suspended - x_api_rate_limited - x_api_unavailable - x_api_unauthorized - x_auth_failure - x_content_too_long - x_daily_limit - x_dm_not_allowed - x_duplicate_action - x_login_auth_failed - x_login_challenge - x_login_denied - x_login_failed - x_login_proxy_error - x_login_rate_limited - x_login_service_unavailable - x_login_suspended - x_rate_limited - x_rejected - x_target_not_found - x_transient_error - x_user_lookup_failed - x_write_ambiguous - x_write_failed message: type: string description: Human-readable error guidance. reason: type: string description: Machine-readable reason for a login cooldown. retryAfter: type: integer minimum: 1 description: Seconds until the next permitted request. retryAfterMs: type: integer minimum: 1 description: Required wait in milliseconds. ContentDisclosure: description: Content disclosure metadata shown by X when a tweet is labeled as paid partnership content or AI-generated media. type: object properties: advertising: type: object properties: isPaidPromotion: type: boolean description: True when X labels the tweet as paid promotion content. aiGenerated: type: object properties: detectionSource: type: string description: Source of the AI-generated media disclosure. hasAiGeneratedMedia: type: boolean description: True when X labels the tweet as containing AI-generated media. PaginatedTweets: description: 'No-mode search, user Tweet, user reply, and direct reply reads use automatic coverage. Shape, filters, aliases, and billing stay compatible. Unprefixed cursors remain legacy. Follow next_cursor while has_next_page is true. An empty filtered page can still have has_next_page true. ' type: object required: - tweets - has_next_page - next_cursor properties: tweets: type: array items: $ref: '#/components/schemas/SearchTweet' has_next_page: type: boolean next_cursor: type: string UserAffiliateLabel: description: Organization affiliation label shown on an X profile. type: object properties: badgeUrl: type: string description: type: string url: type: string urlType: type: string userLabelDisplayType: type: string userLabelType: type: string XWriteActionBilling: type: object additionalProperties: false required: - status - charged - plannedCredits - chargedCredits properties: status: type: string enum: - not_charged - pending - charged - charge_failed - refunded charged: type: boolean plannedCredits: type: string pattern: ^\d+$ chargedCredits: type: string pattern: ^\d+$ description: 'plannedCredits is the approved maximum. chargedCredits comes from the settled credit ledger. Pending or failed writes are not charged. ' IncompleteTweetReplies: allOf: - $ref: '#/components/schemas/TweetReplies' - type: object required: - error - message - nested_replies - diagnostic properties: error: type: string const: replies_incomplete message: type: string has_next_page: type: boolean const: false next_cursor: type: string const: '' UserIdentityVerification: description: Identity verification metadata displayed by X. type: object properties: description: type: string isIdentityVerified: type: boolean verifiedSinceMsec: type: string TweetSearchCoverageResponse: allOf: - $ref: '#/components/schemas/PaginatedTweets' - type: object required: - diagnostic properties: has_next_page: type: boolean const: false next_cursor: type: string const: '' diagnostic: $ref: '#/components/schemas/TweetSearchCoverageDiagnostic' XWriteActionAccount: type: - object - 'null' description: Connected account selected for the write. additionalProperties: false required: - id - username properties: id: type: string username: type: string TweetDetail: description: Full tweet with text, engagement metrics, media, and metadata. A zero metric can mean X did not report the count. type: object required: - id - text - retweetCount - replyCount - likeCount - quoteCount - viewCount - bookmarkCount properties: id: type: string text: type: string createdAt: type: string isNoteTweet: type: boolean description: Whether this is a Note Tweet (long-form post, up to 25,000 characters) isReply: type: boolean description: Whether this tweet is a reply to another tweet isLimitedReply: type: boolean description: Whether replies are limited for this tweet isQuoteStatus: type: boolean description: Whether this tweet quotes another tweet conversationId: type: string description: ID of the root tweet in the conversation thread source: type: string description: Client application used to post this tweet type: type: string description: Tweet result type url: type: string description: Tweet permalink URL lang: type: string description: Tweet language code inReplyToId: type: string description: Tweet ID being replied to inReplyToUserId: type: string description: User ID being replied to inReplyToUsername: type: string description: Username being replied to displayTextRange: type: array items: type: integer description: Start and end offsets for rendered tweet text contentDisclosure: $ref: '#/components/schemas/ContentDisclosure' article: $ref: '#/components/schemas/TweetArticleMetadata' card: $ref: '#/components/schemas/TweetCard' communityNote: $ref: '#/components/schemas/TweetCommunityNote' edit: $ref: '#/components/schemas/TweetEdit' isTranslatable: type: boolean noteTweet: $ref: '#/components/schemas/TweetNote' place: $ref: '#/components/schemas/TweetPlace' possiblySensitive: type: boolean previousCounts: $ref: '#/components/schemas/TweetPreviousCounts' viewState: type: string entities: type: object additionalProperties: true x-stainless-any: true x-stainless-terraform-type: string description: Parsed entities from the tweet text (URLs, mentions, hashtags, media) quoted_tweet: $ref: '#/components/schemas/EmbeddedTweet' retweeted_tweet: $ref: '#/components/schemas/EmbeddedTweet' author: $ref: '#/components/schemas/TweetAuthor' media: type: array items: $ref: '#/components/schemas/TweetMedia' description: Attached media items, omitted when the tweet has no media retweetCount: type: integer replyCount: type: integer likeCount: type: integer quoteCount: type: integer viewCount: type: integer bookmarkCount: type: integer CoverageStopReason: type: string enum: - cursor_failure - deadline - exhausted - failed - page_limit - result_limit - stalled XWriteActionResult: type: - object - 'null' description: Confirmed result produced by the write, when available. additionalProperties: false properties: type: type: string enum: - tweet - direct_message - media - community - state_change id: type: string state: type: string TweetNote: description: Complete Note Tweet content and rich-text metadata. type: object required: - text properties: id: type: string text: type: string isExpandable: type: boolean entities: type: object additionalProperties: true x-stainless-any: true x-stainless-terraform-type: string richtextTags: type: array items: type: object required: - fromIndex - toIndex - types properties: fromIndex: type: integer toIndex: type: integer types: type: array items: type: string UserProfile: description: X user profile with bio, follower counts, and verification status. type: object required: - id - username - name properties: id: type: string username: type: string name: type: string description: type: string followers: type: integer following: type: integer verified: type: boolean isBlueVerified: type: boolean description: Whether X shows a blue verification badge isVerified: type: boolean description: Whether X marks the profile as verified profilePicture: type: string coverPicture: type: string profileBannerUrl: type: string description: Original X profile banner field when available location: type: string createdAt: type: string statusesCount: type: integer mediaCount: type: integer protected: type: boolean description: Whether the profile protects its posts url: type: string favouritesCount: type: integer hasCustomTimelines: type: boolean isTranslator: type: boolean withheldInCountries: type: array items: type: string possiblySensitive: type: boolean pinnedTweetIds: type: array items: type: string isAutomated: type: boolean automatedBy: type: string unavailable: type: boolean unavailableReason: type: string verifiedType: type: string affiliatesHighlightedLabel: $ref: '#/components/schemas/UserAffiliateLabel' businessAccountAffiliatesCount: type: integer creatorSubscriptionsCount: type: integer hasGraduatedAccess: type: boolean hasHiddenSubscriptionsOnProfile: type: boolean highlightsInfo: $ref: '#/components/schemas/UserHighlightsInfo' identityVerification: $ref: '#/components/schemas/UserIdentityVerification' isProfileTranslatable: type: boolean parodyCommentaryFanLabel: type: string profileDescriptionLanguage: type: string profileImageShape: type: string profileInterstitialType: type: string profileSortEnabled: type: boolean profileTranslatorType: type: string superFollowEligible: type: boolean communityRole: type: string description: Community role when returned by community member reads profile_bio: type: object additionalProperties: true x-stainless-any: true x-stainless-terraform-type: string description: Structured profile bio with entity annotations TweetCard: description: Public card metadata attached to a tweet. type: object properties: id: type: string name: type: string url: type: string bindingValues: type: object additionalProperties: true x-stainless-any: true x-stainless-terraform-type: string GuestWalletPurchaseRequest: description: User-confirmed guest wallet checkout request. type: object additionalProperties: false required: - amount_minor - currency properties: amount_minor: type: integer minimum: 1000 maximum: 25000 description: USD cents accepted for this checkout. currency: type: string const: usd UserHighlightsInfo: description: Profile highlight availability and count metadata. type: object properties: canHighlightTweets: type: boolean highlightedTweets: type: string EmbeddedTweet: description: 'Quoted or retweeted tweet context. Every object includes id, text, and engagement metrics. A zero metric can mean X did not report the count. Author, media, and conversation fields appear when available. ' type: object required: - id - text - retweetCount - replyCount - likeCount - quoteCount - viewCount - bookmarkCount properties: id: type: string text: type: string type: type: string createdAt: type: string url: type: string lang: type: string retweetCount: type: integer replyCount: type: integer likeCount: type: integer quoteCount: type: integer viewCount: type: integer bookmarkCount: type: integer isReply: type: boolean isLimitedReply: type: boolean isNoteTweet: type: boolean isQuoteStatus: type: boolean inReplyToId: type: string inReplyToUserId: type: string inReplyToUsername: type: string conversationId: type: string source: type: string displayTextRange: type: array items: type: integer contentDisclosure: $ref: '#/components/schemas/ContentDisclosure' article: $ref: '#/components/schemas/TweetArticleMetadata' card: $ref: '#/components/schemas/TweetCard' communityNote: $ref: '#/components/schemas/TweetCommunityNote' edit: $ref: '#/components/schemas/TweetEdit' isTranslatable: type: boolean noteTweet: $ref: '#/components/schemas/TweetNote' place: $ref: '#/components/schemas/TweetPlace' possiblySensitive: type: boolean previousCounts: $ref: '#/components/schemas/TweetPreviousCounts' viewState: type: string entities: type: object additionalProperties: true x-stainless-any: true x-stainless-terraform-type: string quoted_tweet: $ref: '#/components/schemas/EmbeddedTweet' retweeted_tweet: $ref: '#/components/schemas/EmbeddedTweet' media: type: array items: $ref: '#/components/schemas/TweetMedia' author: $ref: '#/components/schemas/UserProfile' TweetReplies: description: 'Direct reply rows. No-mode requests use resumable automatic coverage. Complete mode also returns nested replies and coverage diagnostics. Keep nested replies separate from direct coverage. ' allOf: - $ref: '#/components/schemas/PaginatedTweets' - type: object properties: nested_replies: type: array items: $ref: '#/components/schemas/SearchTweet' description: Nested replies. Excluded from direct coverage. diagnostic: $ref: '#/components/schemas/ReplyCoverageDiagnostic' GuestWalletCreateCheckoutAction: description: Explicit direct REST action for a new guest wallet checkout. type: object additionalProperties: false required: - account_required - amount_bounds - body - creates - method - path - provider - required_headers - requires_authentication - requires_user_confirmation - requires_user_interaction - response_fields - response_url_field properties: account_required: type: boolean const: false amount_bounds: $ref: '#/components/schemas/GuestWalletAmountBounds' body: $ref: '#/components/schemas/GuestWalletPurchaseRequest' creates: type: string const: checkout_url method: type: string const: POST path: type: string const: /api/v1/guest-wallets provider: type: string deprecated: true const: stripe required_headers: type: object additionalProperties: false required: - Idempotency-Key properties: Idempotency-Key: type: string const: requires_authentication: type: boolean const: false requires_user_confirmation: type: boolean const: true requires_user_interaction: type: boolean const: true response_fields: type: array minItems: 3 maxItems: 3 prefixItems: - type: string const: checkout_url - type: string const: api_key - type: string const: status_url items: type: string enum: - checkout_url - api_key - status_url response_url_field: type: string const: checkout_url ReplyCoverageStrategy: type: object required: - name - pagesAttempted - newDirectReplies - newNestedReplies - stopReason properties: name: type: string pagesAttempted: type: integer minimum: 0 newDirectReplies: type: integer minimum: 0 newNestedReplies: type: integer minimum: 0 stopReason: type: string enum: - deadline - empty_pages - error - missing_cursor - no_next_page - page_cap - repeated_cursor XWriteActionTarget: type: - object - 'null' description: Existing X resource targeted by the write, when applicable. additionalProperties: false required: - type - id properties: type: type: string enum: - tweet - user - community id: type: string TweetMedia: description: Normalized media attached to a tweet. type: object required: - mediaUrl - type - url properties: mediaUrl: type: string description: Media preview URL type: type: string enum: - photo - video - animated_gif url: type: string description: X media link from the tweet allowDownload: type: boolean description: Whether X permits direct media download. altText: type: string description: Accessibility text supplied for the media. aspectRatio: type: array description: Video aspect ratio as width and height. items: type: integer availabilityStatus: type: string description: Media availability state reported by X. displayUrl: type: string description: Display-friendly media URL reported by X. durationMillis: type: integer description: Video duration in milliseconds. expandedUrl: type: string description: Expanded X media URL. faceRects: type: object description: Face-aware crop rectangles grouped by media size. additionalProperties: type: array items: type: object required: - x - y - w - h properties: x: type: integer y: type: integer w: type: integer h: type: integer focusRects: type: array description: Suggested image crops reported by X. items: type: object required: - x - y - w - h properties: x: type: integer y: type: integer w: type: integer h: type: integer height: type: integer description: Original media height. id: type: string description: X media entity ID. indices: type: array description: Media entity offsets in the tweet text. items: type: integer mediaKey: type: string description: Stable X media key. monetizable: type: boolean description: Whether X reports the media as monetizable. sizes: type: object description: Named media renditions and resize modes. additionalProperties: type: object required: - w - h - resize properties: w: type: integer h: type: integer resize: type: string videoVariants: type: array description: Available video encodings, ordered as returned items: type: object required: - contentType - url properties: bitrate: type: integer contentType: type: string url: type: string width: type: integer description: Original media width. GuestWalletAmountBounds: description: Accepted guest wallet purchase range in USD cents. type: object additionalProperties: false required: - currency - maximum_minor - minimum_minor properties: currency: type: string const: usd maximum_minor: type: integer const: 25000 minimum_minor: type: integer const: 1000 TweetPlace: description: Public place metadata attached to a tweet. type: object properties: boundingBox: type: object additionalProperties: true x-stainless-any: true x-stainless-terraform-type: string country: type: string countryCode: type: string fullName: type: string id: type: string name: type: string placeType: type: string url: type: string PaginatedUsers: description: 'Paginated user profiles. No-mode follower, following, and verified follower requests merge independent views automatically. Response fields, page size, aliases, filters, and per-returned-profile billing stay unchanged. Existing unprefixed cursors retain legacy behavior. Follow next_cursor while has_next_page is true. ' type: object required: - users - has_next_page - next_cursor properties: users: type: array items: $ref: '#/components/schemas/UserProfile' has_next_page: type: boolean next_cursor: type: string TweetPreviousCounts: description: Engagement counts retained from a prior tweet edit. type: object properties: bookmarkCount: type: integer likeCount: type: integer quoteCount: type: integer replyCount: type: integer retweetCount: type: integer GuestPaymentRequired: description: 'Credit error for a paid-read guest key with only its accountless guest top-up action. ' type: object additionalProperties: false required: - balance - error - message - next_step - payment_options - required - top_up_endpoint - top_up_url properties: balance: type: string pattern: ^\d+$ error: type: string enum: - insufficient_credits - no_credits - no_subscription - subscription_inactive message: type: string next_step: type: string const: Ask the user to confirm a USD amount before creating checkout. payment_options: type: object additionalProperties: false required: - credits properties: credits: type: object additionalProperties: false required: - create_checkout properties: create_checkout: $ref: '#/components/schemas/GuestWalletTopupCheckoutAction' required: type: string pattern: ^\d+$ top_up_endpoint: type: string const: /api/v1/guest-wallets/topups top_up_url: type: string const: POST /api/v1/guest-wallets/topups XWriteAction: type: object required: - object - id - writeActionId - action - status - terminal - retryable - safeToRetry - statusUrl - pollAfterMs - charged - chargedCredits - billing - request - account - target - targetId - result - nextAction - sendDispatched - success properties: object: type: string const: x_write_action id: type: string writeActionId: type: string action: type: string enum: - create_tweet - delete_tweet - like - unlike - retweet - unretweet - follow - unfollow - remove_follower - send_dm - upload_media - update_profile - update_avatar - update_banner - create_community - delete_community - join_community - leave_community status: type: string enum: - accepted - dispatching - pending_confirmation - success - failed - expired terminal: type: boolean retryable: type: boolean description: True only when a new attempt can reasonably succeed. safeToRetry: type: boolean description: 'True only when no write was dispatched and a new idempotency key may be used. ' statusUrl: type: string pollAfterMs: type: - integer - 'null' minimum: 0 charged: type: boolean chargedCredits: type: string pattern: ^\d+$ billing: $ref: '#/components/schemas/XWriteActionBilling' request: $ref: '#/components/schemas/XWriteActionRequest' account: $ref: '#/components/schemas/XWriteActionAccount' target: $ref: '#/components/schemas/XWriteActionTarget' targetId: type: - string - 'null' result: $ref: '#/components/schemas/XWriteActionResult' nextAction: $ref: '#/components/schemas/XWriteActionNextAction' requestHash: type: string pattern: ^[0-9a-f]{64}$ requestId: type: string idempotent: type: boolean error: type: string message: type: string sendDispatched: type: boolean sendDispatchedAt: type: string format: date-time description: Dispatch timestamp when the write reached execution. createdAt: type: string format: date-time updatedAt: type: string format: date-time completedAt: type: string format: date-time expiresAt: type: string format: date-time description: 'Deadline for resolving a non-terminal write. This is not the Idempotency-Key retention deadline. ' confirmedAt: type: string format: date-time confirmationCheckedAt: type: string format: date-time confirmationAttempts: type: integer minimum: 0 tweetId: type: string description: Compatibility field for a confirmed tweet result ID. messageId: type: string description: Compatibility field for a confirmed direct message ID. mediaId: type: string description: Compatibility field for a confirmed media upload ID. mediaUrl: type: string format: uri description: Public media URL when the upload creates one. communityId: type: string description: Compatibility field for a confirmed community ID. communityName: type: string description: Confirmed community name when available. resultId: type: string description: Compatibility result ID for other write actions. media: type: object additionalProperties: true description: Media count, kind, size, and billing details when used. details: type: object additionalProperties: true description: Structured recovery context for a failed write. success: type: boolean description: 'Durable write lifecycle record. Poll statusUrl until terminal is true. Reusing the original Idempotency-Key returns this same record. Submit a new write only when safeToRetry is true, using a new key. ' TweetCommunityNote: description: Community Note presentation metadata returned by X. type: object properties: id: type: string title: type: string shortTitle: type: string subtitle: type: string footer: type: string destinationUrl: type: string visualStyle: type: string XWriteActionRequest: type: object description: Stable fingerprint and sanitized payload for replay checks. additionalProperties: false required: - hash - payload properties: hash: type: - string - 'null' pattern: ^[0-9a-f]{64}$ description: Stable hash of account, action, target, and payload. payload: type: - object - 'null' additionalProperties: true description: Exact sanitized payload dispatched for this action. ReplyCoverageRichness: description: Field-presence counts across the collected direct replies. type: object required: - totalReplies - text - author - createdAt - language - url - entities - media - article - card - communityNote - quotedOrRepostedTweet - engagementCounts properties: totalReplies: type: integer minimum: 0 description: Total unique direct replies evaluated for richness. text: type: integer minimum: 0 description: Replies with text. author: type: integer minimum: 0 description: Replies with author details. createdAt: type: integer minimum: 0 description: Replies with a creation timestamp. language: type: integer minimum: 0 description: Replies with a language value. url: type: integer minimum: 0 description: Replies with a canonical URL. entities: type: integer minimum: 0 description: Replies with entity metadata. media: type: integer minimum: 0 description: Replies with media metadata. article: type: integer minimum: 0 description: Replies with article content. card: type: integer minimum: 0 description: Replies with card metadata. communityNote: type: integer minimum: 0 description: Replies with community-note data. quotedOrRepostedTweet: type: integer minimum: 0 description: Replies with quoted or reposted tweet data. engagementCounts: type: integer minimum: 0 description: Replies with engagement counts. TweetArticleMetadata: description: Article metadata attached to a tweet. type: object properties: id: type: string title: type: string previewText: type: string coverMediaUrl: type: string AnonymousGuestAuthenticationRequired: description: 'Authentication error for a non-MPP anonymous paid read. The response also offers an optional accountless checkout after confirmation. ' type: object additionalProperties: false required: - account_required - error - message - next_step - payment_options properties: account_required: type: boolean const: false error: type: string const: unauthenticated message: type: string next_step: type: string const: Ask the user to confirm a USD amount before creating checkout. payment_options: type: object additionalProperties: false required: - guest_wallet properties: guest_wallet: type: object additionalProperties: false required: - create_checkout properties: create_checkout: $ref: '#/components/schemas/GuestWalletCreateCheckoutAction' TweetEdit: description: Edit history metadata returned by X. type: object properties: editTweetIds: type: array items: type: string editableUntilMsecs: type: string parameters: TweetFilterMaxId: name: maxId in: query schema: type: string description: Return Tweets older than this Tweet ID. TweetFilterMinFaves: name: minFaves in: query schema: type: integer minimum: 0 description: Minimum likes threshold. minLikes is also accepted. TweetFilterQuotes: name: quotes in: query schema: type: string enum: - include - exclude - only description: Quote mode. TweetFilterGeocode: name: geocode in: query schema: type: string description: Match latitude, longitude, and radius. TweetFilterQuotesOfTweetId: name: quotesOfTweetId in: query schema: type: string description: Only quotes of this tweet ID. TweetFilterFromUser: name: fromUser in: query schema: type: string description: Filter by author username. UserFilterHasWebsite: name: hasWebsite in: query schema: type: boolean description: Only return profiles with a website. TweetFilterSinceDate: name: sinceDate in: query schema: type: string format: date description: Start date in YYYY-MM-DD format. FollowerPageSize: name: pageSize in: query description: 'Maximum user profiles requested from this page (20-200, default 200). Source, filters, or credits can return fewer profiles. Keep requesting next_cursor while has_next_page is true. Deprecated aliases remain accepted. ' schema: type: integer minimum: 20 maximum: 200 default: 200 TweetFilterExactPhrase: name: exactPhrase in: query schema: type: string description: Exact phrase to match. UserFilterMinFollowing: name: minFollowing in: query schema: type: integer minimum: 0 description: Minimum following count. TweetSearchBoundingBox: name: boundingBox in: query schema: type: string description: Geo bounding box, e.g. -74.1 40.6 -73.9 40.8. UserFilterVerifiedType: name: verifiedType in: query schema: type: string description: Match the verification type exactly, ignoring case. UserFilterMaxFollowing: name: maxFollowing in: query schema: type: integer minimum: 0 description: Maximum following count. TweetFilterMaxQuotes: name: maxQuotes in: query schema: type: integer minimum: 0 description: Maximum quotes threshold. TweetFilterCashtags: name: cashtags in: query schema: type: string description: Cashtags separated by spaces, commas, or lines. AutomaticCoverageMode: name: mode in: query schema: type: string enum: - standard - coverage description: 'Omit mode for resumable maximum coverage. Standard keeps legacy pagination. Coverage returns diagnostics once and rejects cursors. ' TweetFilterToUser: name: toUser in: query schema: type: string description: Filter replies sent to a username. UserFilterHasLocation: name: hasLocation in: query schema: type: boolean description: Only return profiles with a location. TweetFilterAnyWords: name: anyWords in: query schema: type: string description: Words or quoted phrases where any one can match. Separate with spaces, commas, or lines. TweetFilterCardName: name: cardName in: query schema: type: string description: Match the Tweet card name. TweetFilterBlueVerifiedOnly: name: blueVerifiedOnly in: query schema: type: boolean description: Only return tweets from Blue-verified authors. UserFilterMinAccountAgeDays: name: minAccountAgeDays in: query schema: type: integer minimum: 0 description: Minimum account age in whole days. TweetFilterSinceId: name: sinceId in: query schema: type: string description: Return Tweets newer than this Tweet ID. UserFilterMinFollowers: name: minFollowers in: query schema: type: integer minimum: 0 description: Minimum follower count. Filtering happens before billing. TweetSearchListId: name: listId in: query schema: type: string description: Search within a list ID. TweetFilterMediaType: name: mediaType in: query schema: type: string enum: - images - videos - gifs - media - links - none description: Filter by media type. TweetFilterVerifiedOnly: name: verifiedOnly in: query schema: type: boolean description: Only return tweets from verified authors. TweetFilterRetweets: name: retweets in: query schema: type: string enum: - include - exclude - only description: Retweet mode. TweetFilterExcludeWords: name: excludeWords in: query schema: type: string description: Words or quoted phrases to exclude. Separate with spaces, commas, or lines. TweetFilterMentioning: name: mentioning in: query schema: type: string description: Filter tweets mentioning a username. TweetFilterMaxRetweets: name: maxRetweets in: query schema: type: integer minimum: 0 description: Maximum retweets threshold. UserFilterUsernameContains: name: usernameContains in: query schema: type: string description: Match a username substring, ignoring case. TweetFilterNews: name: news in: query schema: type: boolean description: Only return news results. TweetFilterInReplyToTweetId: name: inReplyToTweetId in: query schema: type: string description: Only replies to this tweet ID. UserFilterMinStatuses: name: minStatuses in: query schema: type: integer minimum: 0 description: Minimum post count. minPosts is also accepted. TweetSearchPlace: name: place in: query schema: type: string description: Search within a place ID. TweetFilterHashtags: name: hashtags in: query schema: type: string description: Hashtags separated by spaces, commas, or lines. TweetFilterUntilDate: name: untilDate in: query schema: type: string format: date description: End date in YYYY-MM-DD format. TweetFilterMinReplies: name: minReplies in: query schema: type: integer minimum: 0 description: Minimum replies threshold. TweetFilterConversationId: name: conversationId in: query schema: type: string description: Conversation ID filter. UserFilterVerifiedOnly: name: verifiedOnly in: query schema: type: boolean description: Only return verified profiles. AutomaticTweetPageSize: name: pageSize in: query description: 'Automatic pages accept 1-300 Tweets. Standard pages keep 1-100. Default 20. Continue while has_next_page is true. Deprecated aliases remain accepted. ' schema: type: integer minimum: 1 maximum: 300 default: 20 TweetSearchPlaceCountry: name: placeCountry in: query schema: type: string description: Search within a country code. TweetFilterWithin: name: within in: query schema: type: string description: Set the radius for the near filter. UserFilterBioContains: name: bioContains in: query schema: type: string description: 'Match any comma-separated or line-separated bio term, ignoring case. ' UserFilterMaxStatuses: name: maxStatuses in: query schema: type: integer minimum: 0 description: Maximum post count. maxPosts is also accepted. TweetFilterSource: name: source in: query schema: type: string description: Match the source application. TweetFilterNear: name: near in: query schema: type: string description: Match a place name. UserFilterMaxFollowers: name: maxFollowers in: query schema: type: integer minimum: 0 description: Maximum follower count. Missing counts pass this maximum. TweetFilterUrl: name: url in: query schema: type: string description: URL substring or domain filter. TweetFilterMinRetweets: name: minRetweets in: query schema: type: integer minimum: 0 description: Minimum retweets threshold. TweetSearchAdvancedQuery: name: advancedQuery in: query schema: type: string description: Raw advanced search query appended as-is. TweetFilterMinQuotes: name: minQuotes in: query schema: type: integer minimum: 0 description: Minimum quote count threshold. TweetFilterNativeRetweets: name: nativeRetweets in: query schema: type: boolean description: Only return native reposts. TweetFilterMinViews: name: minViews in: query schema: type: integer minimum: 0 description: Minimum view count threshold. TweetFilterRetweetsOfTweetId: name: retweetsOfTweetId in: query schema: type: string description: Only retweets of this tweet ID. TweetSearchPointRadius: name: pointRadius in: query schema: type: string description: Geo point radius, e.g. -73.99 40.73 25mi. TweetFilterReplies: name: replies in: query schema: type: string enum: - include - exclude - only description: Reply mode. TweetFilterMaxFaves: name: maxFaves in: query schema: type: integer minimum: 0 description: Maximum likes threshold. maxLikes is also accepted. TweetFilterMinBookmarks: name: minBookmarks in: query schema: type: integer minimum: 0 description: Minimum bookmark count threshold. ResultPageSize: name: pageSize in: query description: 'Maximum page items (1-100, default 20). Source, filters, or credits can reduce results. Continue while has_next_page is true. Deprecated limit and count aliases remain accepted. ' schema: type: integer minimum: 1 maximum: 100 default: 20 AutomaticCoverageCursor: name: cursor in: query schema: type: string description: 'Cursor from the previous response. Xquik cursors resume automatic coverage. Existing unprefixed cursors keep legacy standard behavior. ' UserFilterLocationContains: name: locationContains in: query schema: type: string description: Match a location substring, ignoring case. TweetFilterWithinTime: name: withinTime in: query schema: type: string description: Match Tweets inside a recent time window. TweetFilterMaxReplies: name: maxReplies in: query schema: type: integer minimum: 0 description: Maximum replies threshold. TweetFilterExcludeSource: name: excludeSource in: query schema: type: string description: Exclude a source application. TweetFilterLanguage: name: language in: query schema: type: string description: Language code filter, e.g. en or tr. TweetFilterSafe: name: safe in: query schema: type: boolean description: Enable the safe-search filter. responses: FavoritersUnavailable: description: 'X reports likes for the post but does not expose the corresponding user identities. Returns error code `favoriters_unavailable`. ' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: favoriters_unavailable message: Users who liked this post are unavailable. Use retweeters or replies instead. AnonymousGuestAuthenticationRequired: description: 'Authentication required for a non-MPP paid read. The challenge requests Bearer authentication, not payment. Missing credentials advertise guest checkout without creating it. Invalid credentials return a plain error. Require user confirmation before calling an advertised action. ' headers: Cache-Control: description: Prevents storage of the guest checkout action. schema: type: string const: no-store WWW-Authenticate: description: Bearer authentication challenge, not a Payment challenge. schema: type: string const: Bearer realm="xquik" content: application/json: schema: oneOf: - $ref: '#/components/schemas/AnonymousGuestAuthenticationRequired' - allOf: - $ref: '#/components/schemas/Error' - not: required: - payment_options example: account_required: false error: unauthenticated message: Authentication required. next_step: Ask the user to confirm a USD amount before creating checkout. payment_options: guest_wallet: create_checkout: account_required: false amount_bounds: currency: usd maximum_minor: 25000 minimum_minor: 1000 body: amount_minor: 1000 currency: usd creates: checkout_url method: POST path: /api/v1/guest-wallets provider: stripe required_headers: Idempotency-Key: requires_authentication: false requires_user_confirmation: true requires_user_interaction: true response_fields: - checkout_url - api_key - status_url response_url_field: checkout_url UnexpectedError: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. MaximumCoverageBusy: description: Automatic or explicit maximum coverage is temporarily busy. headers: Retry-After: schema: type: integer minimum: 1 description: Seconds to wait before retrying. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: x_api_unavailable message: Maximum coverage is busy. Retry shortly. RateLimitExceeded: description: 'Xquik tier rate limit exceeded. The response includes a `Retry-After` header with the number of seconds to wait before retrying. ' content: application/json: schema: allOf: - $ref: '#/components/schemas/Error' - type: object properties: retryAfter: type: integer example: 60 example: error: rate_limit_exceeded message: Too many requests. Try again later. retryAfter: 60 headers: Retry-After: description: Seconds until the next permitted request. schema: example: 60 minimum: 1 type: integer InvalidInput: description: Invalid input content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid_input message: Invalid input. Check the request body. PaymentRequired: description: 'Payment required. MPP reads return a problem document and `WWW-Authenticate`. Authenticated reads return balances and checkout actions. Guest keys receive only the guest top-up action. Other endpoints may use legacy errors. A failed request never creates checkout. Require user confirmation before creating one. ' headers: WWW-Authenticate: description: MPP payment challenge for eligible anonymous pay-per-use requests. Authenticated credit or subscription errors omit this header. schema: type: string content: application/json: schema: oneOf: - $ref: '#/components/schemas/XWritePaymentRequired' - $ref: '#/components/schemas/AuthenticatedPaymentRequired' - $ref: '#/components/schemas/GuestPaymentRequired' - allOf: - $ref: '#/components/schemas/Error' - not: required: - payment_options example: balance: '0' dashboard: /dashboard/account error: insufficient_credits message: Insufficient credits. Top up or subscribe to continue. next_step: Ask the user to confirm a payment option before creating checkout. payment_options: credits: create_checkout: body: dollars: 10 locale: en creates: checkout_url method: POST path: /api/v1/credits/topup provider: stripe requires_authentication: true requires_user_confirmation: true response_url_field: url subscription: create_checkout: body: tier: starter creates: checkout_url method: POST path: /api/v1/subscribe provider: stripe requires_authentication: true requires_user_confirmation: true response_url_field: url required: '1' top_up_endpoint: /api/v1/credits/topup top_up_url: POST /api/v1/credits/topup application/problem+json: schema: $ref: '#/components/schemas/MppPaymentRequired' example: account_required: false challengeId: Opaque MPP challenge identifier detail: Payment is required. hint: Use a supported wallet with an offer from the WWW-Authenticate header. status: 402 title: Payment Required type: https://paymentauth.org/problems/payment-required next_step: Ask the user to confirm a USD amount before creating checkout. payment_options: guest_wallet: create_checkout: account_required: false amount_bounds: currency: usd maximum_minor: 25000 minimum_minor: 1000 body: amount_minor: 1000 currency: usd creates: checkout_url method: POST path: /api/v1/guest-wallets provider: stripe required_headers: Idempotency-Key: requires_authentication: false requires_user_confirmation: true requires_user_interaction: true response_fields: - checkout_url - api_key - status_url response_url_field: checkout_url XApiError: description: 'Dependency unavailable, unauthorized, or rate limited. Default v1 returns 502. The best-practice response contract returns 424 for transparent dependency failures. ' content: application/json: schema: $ref: '#/components/schemas/Error' example: error: x_api_unavailable message: X data source temporarily unavailable. Try again later. Unauthenticated: description: Unauthenticated headers: Cache-Control: description: Prevents storage of authentication responses. schema: type: string const: no-store WWW-Authenticate: description: Bearer authentication challenge. schema: type: string const: Bearer realm="xquik" content: application/json: schema: $ref: '#/components/schemas/Error' example: error: unauthenticated message: Authentication required. Provide a valid API key or bearer token. CursorGone: description: Restart without the `coverage_cursor_gone` cursor. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: coverage_cursor_gone message: Cursor finished, expired, or superseded. Restart pagination without cursor. CoverageCursorUnavailable: description: Cursor is in use. Retry `coverage_cursor_unavailable` later. headers: Retry-After: required: true schema: type: integer minimum: 1 description: Seconds to wait. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: coverage_cursor_unavailable message: Cursor busy. Retry after the indicated delay. RepliesIncomplete: description: Incomplete replies content: application/json: schema: anyOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/IncompleteTweetReplies' example: error: replies_incomplete message: Replies are incomplete. Retry complete mode later. tweets: [] has_next_page: false next_cursor: '' nested_replies: [] diagnostic: complete: false reportedReplyCount: 100 targetDirectReplies: 80 uniqueDirectReplies: 42 coveragePercentage: 42 nestedReplyCount: 5 pagesAttempted: 12 strategiesAttempted: [] duplicateCount: 3 cursorFailures: 0 repeatedCursorCount: 0 emptyFalseProgressPages: 1 malformedCount: 0 unrelatedCount: 2 missingResponseModulesOrFields: [] recommendedFallback: Retry complete mode later. X did not expose enough direct replies. richness: totalReplies: 42 text: 42 author: 40 createdAt: 42 language: 38 url: 42 entities: 20 media: 5 article: 0 card: 2 communityNote: 0 quotedOrRepostedTweet: 1 engagementCounts: 42 responseTruncated: false securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: 'Xquik API key passed through the x-api-key header. Xquik-Api-Key is a vendor-prefixed alias. API keys beginning with xq_ can also use Authorization: Bearer.' oauthBearer: type: http scheme: bearer description: 'OAuth 2.1 access token passed through Authorization: Bearer. Values beginning with xq_ remain Xquik API-key credentials, not OAuth tokens.' cookieSession: type: apiKey in: cookie name: __Host-xquik_session description: Secure Xquik browser session cookie. x-service-info: categories: - data docs: homepage: https://xquik.com apiReference: https://docs.xquik.com llms: https://docs.xquik.com/llms.txt x-discovery: ownershipProofs: - dns:xquik.com