openapi: 3.2.0 info: title: Xquik Tweets API version: '1.0' description: "Xquik is an independent third-party service. Not affiliated with X Corp. \"Twitter\" and \"X\" are trademarks of X Corp. Look up tweets, users, and X trends. Search tweets, check follow relationships, download media, and monitor accounts. 33 paid-read endpoints accept prepaid credits without a subscription. 7 fixed-price lookups also accept direct MPP payments. Write and automation endpoints require an API key or OAuth 2.1 bearer token.\n\n## Xquik SDKs\n\nStainless generates each SDK from this OpenAPI schema. Pick a language:\n\n- TypeScript / Node.js: `npm i x-twitter-scraper` -\n [Xquik-dev/x-twitter-scraper-typescript](https://github.com/Xquik-dev/x-twitter-scraper-typescript)\n\n- Python: `pip install x-twitter-scraper` -\n [Xquik-dev/x-twitter-scraper-python](https://github.com/Xquik-dev/x-twitter-scraper-python)\n\n- Go: `go get github.com/Xquik-dev/x-twitter-scraper-go` -\n [Xquik-dev/x-twitter-scraper-go](https://github.com/Xquik-dev/x-twitter-scraper-go)\n\n- Ruby: `gem install x-twitter-scraper` -\n [Xquik-dev/x-twitter-scraper-ruby](https://github.com/Xquik-dev/x-twitter-scraper-ruby)\n\n- Java (source build; Maven Central pending) -\n [Xquik-dev/x-twitter-scraper-java](https://github.com/Xquik-dev/x-twitter-scraper-java)\n\n- Kotlin (source build; Maven Central pending) -\n [Xquik-dev/x-twitter-scraper-kotlin](https://github.com/Xquik-dev/x-twitter-scraper-kotlin)\n\n- C# / .NET: `dotnet add package XTwitterScraper` -\n [Xquik-dev/x-twitter-scraper-csharp](https://github.com/Xquik-dev/x-twitter-scraper-csharp)\n\n- PHP: `composer require xquik/x-twitter-scraper` -\n [Xquik-dev/x-twitter-scraper-php](https://github.com/Xquik-dev/x-twitter-scraper-php)\n\n- CLI: `go install github.com/Xquik-dev/x-twitter-scraper-cli/cmd/x-twitter-scraper@latest` -\n [Xquik-dev/x-twitter-scraper-cli](https://github.com/Xquik-dev/x-twitter-scraper-cli)\n\n- Terraform Provider (Terraform Registry) -\n [Xquik-dev/terraform-provider-x-twitter-scraper](https://github.com/Xquik-dev/terraform-provider-x-twitter-scraper)\n\n\nOpenClaw plugin: [Xquik-dev/tweetclaw](https://github.com/Xquik-dev/tweetclaw) (`openclaw plugins install clawhub:@xquik/tweetclaw`)." x-guidance: '## Common tasks **Find a tweet** - GET /x/tweets/{id} with a numeric tweet ID. Returns full tweet data: text, author, metrics (likes, retweets, replies, views), media URLs, and creation timestamp. Cost: $0.00015 per lookup. **Search tweets** - GET /x/tweets/search?q={query}&limit={n}. Supports X search operators, structured filters like fromUser, mediaType, minFaves, hashtags, and verifiedOnly, plus exact lookup for a pasted Tweet ID or X status URL. Plain from:user date windows are optimized for timeline completeness. Returns up to 200 tweets per page with cursor-based pagination. Cost: $0.00015 per tweet returned. **Find a user** - GET /x/users/{id} where {id} is a numeric user ID or @username. Returns profile data: name, bio, follower/following counts, verification status, join date. Cost: $0.00015 per lookup. **Check if A follows B** - GET /x/followers/check?source={a}&target={b} where source and target are usernames, @usernames, or X or Twitter profile URLs. Cost: $0.00075. **Get trending topics** - GET /trends?woeid={region}&count={n}. WOEID 1 = worldwide, 23424977 = US, 23424975 = UK, 23424969 = Turkey. Cost: $0.00045. **Download media** - POST /x/media/download with {"tweetIds": ["123", "456"]} body. Returns download URLs for images and videos. Cost: 1 credit per fresh tweet processed with media; cached repeat downloads are free. **Read an article** - GET /x/articles/{tweetId} for long-form X Articles. Returns full article HTML, cover image, and metadata. Cost: $0.00075. ## Pagination Default v1 responses keep their existing pagination fields for compatibility. Platform list endpoints return `hasMore` and `nextCursor`; X data endpoints return `has_next_page` and `next_cursor`. Send `xquik-api-contract: 2026-04-29` to receive the unified best-practice fields `has_more` and `next_cursor`. Pass the cursor back as `?cursor={cursor}`; legacy `?after={cursor}` still works. Dynamic-priced endpoints charge per item returned, not per request. ## Authentication Eligible paid read endpoints accept accountless prepaid credit wallets. Fixed-price lookups also accept direct MPP payments. Media downloads, write endpoints, and automation features require authentication. Send an Xquik API key through `x-api-key`, `Xquik-Api-Key`, or `Authorization: Bearer xq_...`. Send an OAuth 2.1 access token through `Authorization: Bearer`. ## Best-Practice Response Contract v1 keeps its original response contract by default so existing integrations do not break. Send `xquik-api-contract: 2026-04-29` to opt in to the best-practice contract: snake_case response fields, Unix timestamps in seconds, structured error objects, `has_more` and `next_cursor` pagination fields, `object` resource identifiers, and prefixed IDs where available. Dependency failures that returned 502 in default v1 return 424 in the opt-in contract. Future major API versions should make this contract the default.' 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: List of tweets 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: true next_cursor: DAACCgACGRElMJcAAA '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: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. 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 tags: - Tweets security: - apiKey: [] - oauthBearer: [] - {} parameters: - name: q in: query required: true schema: type: string description: Search query (keywords, - name: queryType in: query required: false schema: type: string enum: - Latest - Top default: Latest description: Sort order - Latest (chronological) or Top (engagement-ranked) - name: cursor in: query schema: type: string description: Pagination cursor from previous response - name: sinceTime in: query schema: type: string description: ISO 8601 timestamp - only return tweets after this time - name: untilTime in: query schema: type: string description: ISO 8601 timestamp - only return tweets before this time - name: limit in: query required: false schema: type: integer default: 20 maximum: 200 description: 'Max tweets to return (server paginates internally). Omit for single page (~20). This is an upper bound for paid authenticated calls: remaining credits can reduce the returned page size, and zero affordable results returns 402 insufficient_credits. ' - $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/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: $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: 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' '424': $ref: '#/components/responses/XApiError' '429': $ref: '#/components/responses/RateLimitExceeded' '502': $ref: '#/components/responses/XApiError' default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Search tweets by query, Tweet ID, X status URL, or account date window. /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: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. 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' 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: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. /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: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. 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: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. 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: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. 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 - name: cursor in: query schema: type: string description: Pagination cursor for quote tweets - $ref: '#/components/parameters/ResultPageSize' - 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/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: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. 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. Complete mode merges available timeline views, supported rankings, every forward cursor module, labeled hidden-content branches, exact-parent time partitions scaled to the reported reply count, and search. It separates nested replies and returns 424 below 80% coverage. ' tags: - Tweets security: - apiKey: [] - oauthBearer: [] - {} parameters: - name: id in: path required: true schema: type: string description: Tweet ID to get replies - name: cursor in: query schema: type: string description: Pagination cursor for tweet replies - name: mode in: query schema: type: string enum: - standard - complete default: standard description: 'Use standard for pagination and filters. Use complete for maximum coverage. Complete mode accepts only limit. Remove other pagination and filter parameters. ' - 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). Without complete mode, this is the deprecated pageSize alias and accepts only 1-100. ' - $ref: '#/components/parameters/ResultPageSize' - 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/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' '424': $ref: '#/components/responses/RepliesIncomplete' '429': $ref: '#/components/responses/RateLimitExceeded' '502': $ref: '#/components/responses/XApiError' '503': description: Complete reply extraction 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: Complete reply extraction is busy. Retry shortly. default: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. /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' 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: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. 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' 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: content: application/json: example: error: internal_error message: Unexpected error. Try again. schema: $ref: '#/components/schemas/Error' description: Unexpected error. description: Get full conversation thread for a tweet. components: parameters: TweetFilterExactPhrase: name: exactPhrase in: query schema: type: string description: Exact phrase to match. TweetSearchBoundingBox: name: boundingBox in: query schema: type: string description: Geo bounding box, e.g. -74.1 40.6 -73.9 40.8. 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 TweetFilterReplies: name: replies in: query schema: type: string enum: - include - exclude - only description: Reply mode. TweetFilterMinRetweets: name: minRetweets in: query schema: type: integer minimum: 0 description: Minimum retweets threshold. TweetSearchListId: name: listId in: query schema: type: string description: Search within a list ID. TweetSearchPlaceCountry: name: placeCountry in: query schema: type: string description: Search within a country code. TweetFilterHashtags: name: hashtags in: query schema: type: string description: Hashtags separated by spaces, commas, or lines. TweetFilterConversationId: name: conversationId in: query schema: type: string description: Conversation ID filter. TweetFilterInReplyToTweetId: name: inReplyToTweetId in: query schema: type: string description: Only replies to this tweet ID. TweetSearchPointRadius: name: pointRadius in: query schema: type: string description: Geo point radius, e.g. -73.99 40.73 25mi. TweetFilterFromUser: name: fromUser in: query schema: type: string description: Filter by author username. TweetFilterMinQuotes: name: minQuotes in: query schema: type: integer minimum: 0 description: Minimum quote count threshold. TweetFilterQuotesOfTweetId: name: quotesOfTweetId in: query schema: type: string description: Only quotes of this tweet ID. TweetFilterMentioning: name: mentioning in: query schema: type: string description: Filter tweets mentioning a username. TweetFilterMediaType: name: mediaType in: query schema: type: string enum: - images - videos - gifs - media - links - none description: Filter by media type. FollowerPageSize: name: pageSize in: query description: 'Maximum user profiles requested from this page (20-200, default 200). The response can contain fewer profiles because the source returned fewer or remaining credits cover fewer results. Keep requesting next_cursor while has_next_page is true. The deprecated limit and count aliases remain accepted. ' schema: type: integer minimum: 20 maximum: 200 default: 200 TweetFilterMinReplies: name: minReplies in: query schema: type: integer minimum: 0 description: Minimum replies threshold. TweetFilterSinceDate: name: sinceDate in: query schema: type: string format: date description: Start date in YYYY-MM-DD format. TweetFilterCashtags: name: cashtags in: query schema: type: string description: Cashtags separated by spaces, commas, or lines. TweetSearchAdvancedQuery: name: advancedQuery in: query schema: type: string description: Raw advanced search query appended as-is. TweetFilterUntilDate: name: untilDate in: query schema: type: string format: date description: End date in YYYY-MM-DD format. TweetFilterAnyWords: name: anyWords in: query schema: type: string description: Words or quoted phrases where any one can match. Separate with spaces, commas, or lines. TweetFilterQuotes: name: quotes in: query schema: type: string enum: - include - exclude - only description: Quote mode. TweetFilterToUser: name: toUser in: query schema: type: string description: Filter replies sent to a username. TweetFilterRetweetsOfTweetId: name: retweetsOfTweetId in: query schema: type: string description: Only retweets of this tweet ID. TweetFilterRetweets: name: retweets in: query schema: type: string enum: - include - exclude - only description: Retweet mode. TweetFilterUrl: name: url in: query schema: type: string description: URL substring or domain filter. TweetFilterVerifiedOnly: name: verifiedOnly in: query schema: type: boolean description: Only return tweets from verified authors. TweetFilterExcludeWords: name: excludeWords in: query schema: type: string description: Words or quoted phrases to exclude. Separate with spaces, commas, or lines. TweetFilterMinFaves: name: minFaves in: query schema: type: integer minimum: 0 description: Minimum likes threshold. TweetSearchPlace: name: place in: query schema: type: string description: Search within a place ID. TweetFilterLanguage: name: language in: query schema: type: string description: Language code filter, e.g. en or tr. responses: PaymentRequired: description: 'Payment required. Fixed-price direct MPP requests return a Machine Payments Protocol problem document and a WWW-Authenticate challenge. Authenticated X data requests return balances and explicit Stripe checkout-creation actions. Guest paid-read keys receive only the accountless guest top-up action. Direct MPP challenges also advertise the Stripe wallet action. Other authenticated endpoints return a legacy error shape. A failed request never creates checkout. Create checkout only after the user confirms a payment option. ' 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 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. RepliesIncomplete: description: Incomplete replies content: application/json: schema: anyOf: - $ref: '#/components/schemas/Error' - $ref: '#/components/schemas/IncompleteTweetReplies' 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 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. InvalidInput: description: Invalid input content: application/json: schema: $ref: '#/components/schemas/Error' example: error: invalid_input message: Invalid input. Check the request body. AnonymousGuestAuthenticationRequired: description: 'Authentication required for a non-MPP paid read. The Bearer challenge requests authentication and is not a Payment challenge. Requests without credentials advertise accountless Stripe checkout, but create no checkout. Explicit invalid credentials return the plain error shape. Call an advertised action only after explicit user confirmation. ' 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 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. schemas: 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. example: 1000 currency: type: string const: usd PaginatedUsers: description: 'Paginated user profiles. The item count can be lower than pageSize when the source returns fewer profiles or remaining credits cover fewer results. Follow next_cursor while has_next_page is true. A relationship can naturally contain fewer profiles than requested. Zero affordable results returns 402 insufficient_credits. ' type: object required: - users - has_next_page - next_cursor properties: users: type: array items: $ref: '#/components/schemas/UserProfile' example: - id: '9876543210' username: elonmusk name: Elon Musk has_next_page: type: boolean example: true next_cursor: type: string example: DAACCgACGRElMJcAAA 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 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 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. 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 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 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 example: '1234567890' text: type: string example: Just launched our new feature! createdAt: type: string example: '2025-01-15T12:00:00Z' isNoteTweet: type: boolean description: Whether this is a Note Tweet (long-form post, up to 25,000 characters) example: false isReply: type: boolean description: Whether this tweet is a reply to another tweet example: false isLimitedReply: type: boolean description: Whether replies are limited for this tweet example: false isQuoteStatus: type: boolean description: Whether this tweet quotes another tweet example: false conversationId: type: string description: ID of the root tweet in the conversation thread example: '1234567890' source: type: string description: Client application used to post this tweet example: Twitter Web App type: type: string description: Tweet result type example: tweet url: type: string description: Tweet permalink URL example: https://x.com/example_user/status/1234567890 lang: type: string description: Tweet language code example: en inReplyToId: type: string description: Tweet ID being replied to example: '1234567890' inReplyToUserId: type: string description: User ID being replied to example: '9876543210' inReplyToUsername: type: string description: Username being replied to example: example_user displayTextRange: type: array items: type: integer description: Start and end offsets for rendered tweet text example: - 0 - 31 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 example: 5 replyCount: type: integer example: 3 likeCount: type: integer example: 42 quoteCount: type: integer example: 1 viewCount: type: integer example: 1500 bookmarkCount: type: integer example: 2 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 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 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 example: '12345' writeActionId: type: string example: '12345' action: type: string example: like 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 example: success enum: - accepted - dispatching - pending_confirmation - success - failed - expired terminal: type: boolean example: true retryable: type: boolean description: True only when a new attempt can reasonably succeed. example: false safeToRetry: type: boolean description: 'True only when no write was dispatched and a new idempotency key may be used. ' example: false statusUrl: type: string example: /api/v1/x/write-actions/12345 pollAfterMs: type: - integer - 'null' minimum: 0 example: null charged: type: boolean example: true chargedCredits: type: string pattern: ^\d+$ example: '10' billing: $ref: '#/components/schemas/XWriteActionBilling' request: $ref: '#/components/schemas/XWriteActionRequest' account: $ref: '#/components/schemas/XWriteActionAccount' target: $ref: '#/components/schemas/XWriteActionTarget' targetId: type: - string - 'null' example: '9876543210' result: $ref: '#/components/schemas/XWriteActionResult' nextAction: $ref: '#/components/schemas/XWriteActionNextAction' requestHash: type: string pattern: ^[0-9a-f]{64}$ example: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef requestId: type: string example: 01JZ8R7QSC9QKT0V7JX4M2A6B8 idempotent: type: boolean example: false error: type: string example: x_write_ambiguous message: type: string example: Invalid input. Check request fields. sendDispatched: type: boolean example: true sendDispatchedAt: type: string format: date-time description: Dispatch timestamp when the write reached execution. example: '2026-07-21T05:00:00Z' createdAt: type: string format: date-time example: '2026-07-21T05:00:00Z' updatedAt: type: string format: date-time example: '2026-07-21T05:00:02Z' completedAt: type: string format: date-time example: '2026-07-21T05:00:02Z' expiresAt: type: string format: date-time description: 'Deadline for resolving a non-terminal write. This is not the Idempotency-Key retention deadline. ' example: '2026-07-22T05:00:00Z' confirmedAt: type: string format: date-time example: '2026-07-21T05:00:02Z' confirmationCheckedAt: type: string format: date-time example: '2026-07-21T05:00:02Z' confirmationAttempts: type: integer minimum: 0 example: 1 tweetId: type: string description: Compatibility field for a confirmed tweet result ID. example: '9876543210' messageId: type: string description: Compatibility field for a confirmed direct message ID. example: '1234567890' mediaId: type: string description: Compatibility field for a confirmed media upload ID. example: '2345678901' mediaUrl: type: string format: uri description: Public media URL when the upload creates one. example: https://media.xquik.com/example.jpg communityId: type: string description: Compatibility field for a confirmed community ID. example: '3456789012' communityName: type: string description: Confirmed community name when available. example: Builders resultId: type: string description: Compatibility result ID for other write actions. example: '9876543210' media: type: object additionalProperties: true description: Media count, kind, size, and billing details when used. example: count: 1 kind: image details: type: object additionalProperties: true description: Structured recovery context for a failed write. example: suggestion: Poll the action status URL. success: type: boolean example: true 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. ' 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' 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+$ example: '0' error: type: string enum: - insufficient_credits - no_credits - no_subscription - subscription_inactive example: insufficient_credits message: type: string example: Insufficient credits. Top up or subscribe to continue. 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+$ example: '1' top_up_endpoint: type: string const: /api/v1/guest-wallets/topups top_up_url: type: string const: POST /api/v1/guest-wallets/topups UserHighlightsInfo: description: Profile highlight availability and count metadata. type: object properties: canHighlightTweets: type: boolean highlightedTweets: type: string TweetAuthor: description: Tweet author profile. The lookup route always includes follower count and verification state. Other profile fields appear when available. example: id: '9876543210' username: elonmusk name: Elon Musk followers: 150000000 verified: true allOf: - $ref: '#/components/schemas/UserProfile' - title: TweetAuthorRequirements type: object required: - followers - verified properties: followers: type: integer minimum: 0 example: 150000000 verified: type: boolean example: true XWriteActionBilling: type: object additionalProperties: false required: - status - charged - plannedCredits - chargedCredits properties: status: type: string enum: - not_charged - pending - charged - charge_failed - refunded example: charged charged: type: boolean example: true plannedCredits: type: string pattern: ^\d+$ example: '10' chargedCredits: type: string pattern: ^\d+$ example: '10' description: 'plannedCredits is the approved maximum. chargedCredits comes from the settled credit ledger. Pending or failed writes are not charged. ' example: status: charged charged: true plannedCredits: '10' chargedCredits: '10' UserProfile: description: X user profile with bio, follower counts, and verification status. type: object required: - id - username - name properties: id: type: string example: '9876543210' username: type: string example: elonmusk name: type: string example: Elon Musk description: type: string example: CEO of Tesla, SpaceX, and X followers: type: integer example: 150000000 following: type: integer example: 500 verified: type: boolean example: true isBlueVerified: type: boolean description: Whether X shows a blue verification badge example: true isVerified: type: boolean description: Whether X marks the profile as verified example: true profilePicture: type: string example: https://pbs.twimg.com/profile_images/example.jpg coverPicture: type: string example: https://pbs.twimg.com/profile_banners/example.jpg profileBannerUrl: type: string description: Original X profile banner field when available example: https://pbs.twimg.com/profile_banners/example.jpg location: type: string example: Austin, TX createdAt: type: string example: '2009-06-02T20:12:29Z' statusesCount: type: integer example: 35000 mediaCount: type: integer example: 1200 protected: type: boolean description: Whether the profile protects its posts example: false url: type: string example: https://xquik.com favouritesCount: type: integer example: 18000 hasCustomTimelines: type: boolean example: true isTranslator: type: boolean example: false withheldInCountries: type: array items: type: string example: - DE possiblySensitive: type: boolean example: false pinnedTweetIds: type: array items: type: string example: - '1234567890' isAutomated: type: boolean example: false automatedBy: type: string example: example_user unavailable: type: boolean example: false unavailableReason: type: string example: suspended verifiedType: type: string example: Business 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 example: Member profile_bio: type: object additionalProperties: true x-stainless-any: true x-stainless-terraform-type: string description: Structured profile bio with entity annotations example: description: CEO of Tesla, SpaceX, and X entities: urls: [] AuthenticatedPaymentRequired: description: Authenticated credit or subscription error with confirmation-gated Stripe 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. example: '0' 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 example: insufficient_credits message: type: string example: Insufficient credits. Top up or subscribe to continue. 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 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 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. example: '1' top_up_endpoint: type: string const: /api/v1/credits/topup top_up_url: type: string const: POST /api/v1/credits/topup TweetEdit: description: Edit history metadata returned by X. type: object properties: editTweetIds: type: array items: type: string editableUntilMsecs: type: string 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 XWritePaymentRequired: allOf: - $ref: '#/components/schemas/XWriteAction' - type: object required: - error - message description: 'Durable failed write action with the applicable payment guidance. ' XWriteActionAccount: type: - object - 'null' description: Connected account selected for the write. additionalProperties: false required: - id - username properties: id: type: string username: type: string example: id: '42' username: example 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. example: true aiGenerated: type: object properties: detectionSource: type: string description: Source of the AI-generated media disclosure. example: UserDeclared hasAiGeneratedMedia: type: boolean description: True when X labels the tweet as containing AI-generated media. example: true 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 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 example: '1234567890' text: type: string example: Just launched our new feature! type: type: string example: tweet createdAt: type: string example: '2025-01-15T12:00:00Z' isNoteTweet: type: boolean description: True for Note Tweets (long-form content, up to 25,000 characters) example: false isReply: type: boolean description: True when this search result is a reply example: false isQuoteStatus: type: boolean description: True when this search result quotes another tweet example: false isLimitedReply: type: boolean description: Whether the tweet has limited reply permissions example: false inReplyToId: type: string description: ID of the tweet this result replies to. example: '1234567890' inReplyToUserId: type: string description: ID of the user this result replies to. example: '9876543210' inReplyToUsername: type: string description: Username this result replies to. example: example_user conversationId: type: string description: Root tweet ID for the search result conversation example: '1234567890' source: type: string description: Client application used to post the tweet example: Twitter Web App displayTextRange: type: array items: type: integer description: Rendered text's start and end offsets. example: - 0 - 31 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. example: https://x.com/example_user/status/1234567890 lang: type: string description: Search result language code. example: en likeCount: type: integer example: 42 retweetCount: type: integer example: 5 replyCount: type: integer example: 3 quoteCount: type: integer example: 1 viewCount: type: integer example: 1500 bookmarkCount: type: integer example: 2 author: $ref: '#/components/schemas/UserProfile' TweetReplies: description: 'Reply rows. 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' PaginatedTweets: description: 'Paginated tweets. Source visibility, filters, or remaining credits can reduce results. An empty filtered page can still have has_next_page true. Follow next_cursor while has_next_page is true. Zero affordable results returns 402 insufficient_credits. ' type: object required: - tweets - has_next_page - next_cursor properties: tweets: type: array items: $ref: '#/components/schemas/SearchTweet' example: - id: '1234567890' text: Just launched our new feature! retweetCount: 5 replyCount: 3 likeCount: 42 quoteCount: 1 viewCount: 1500 bookmarkCount: 2 has_next_page: type: boolean example: true next_cursor: type: string example: DAACCgACGRElMJcAAA 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 example: type: poll url: /api/v1/x/write-actions/12345 afterMs: 2000 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. example: hash: 0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef payload: tweet_id: '9876543210' 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 example: type: tweet id: '9876543210' 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 MppPaymentRequired: description: Anonymous payment requirement for a direct MPP operation. The response includes an MPP challenge and an accountless Stripe 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. example: mpp_challenge_example detail: type: string example: Payment is required. hint: type: string description: Instructions for selecting and paying an MPP offer. example: Use a supported wallet with an offer from the WWW-Authenticate header. 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 AnonymousGuestAuthenticationRequired: description: 'Authentication error for a non-MPP anonymous paid read. The response also advertises optional accountless Stripe 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 example: Authentication required. 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' 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: '' 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 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. 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 example: invalid_input 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 - 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 - 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 - draft_not_found - favoriters_unavailable - forbidden - guest_wallet_unavailable - guest_wallets_disabled - guest_wallets_unavailable - idempotency_conflict - idempotency_key_conflict - invalid_community_id - invalid_idempotency_key - invalid_list_id - invalid_payment_amount - invalid_range - login_rate_limited - missing_idempotency_key - missing_ids - no_cached_style - passkey_required - rate_limited - read_request_timeout - replies_incomplete - support_media_rate_limit - support_request_rate_limit - too_many_ids - 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 example: invalid_input - type: object title: StructuredError required: - message - type - code properties: message: type: string example: Invalid input. Check the request body. type: type: string enum: - api_error - authentication_error - billing_error - dependency_error - invalid_request_error - permission_error - rate_limit_error example: invalid_request_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 - 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 - 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 - draft_not_found - favoriters_unavailable - forbidden - guest_wallet_unavailable - guest_wallets_disabled - guest_wallets_unavailable - idempotency_conflict - idempotency_key_conflict - invalid_community_id - invalid_idempotency_key - invalid_list_id - invalid_payment_amount - invalid_range - login_rate_limited - missing_idempotency_key - missing_ids - no_cached_style - passkey_required - rate_limited - read_request_timeout - replies_incomplete - support_media_rate_limit - support_request_rate_limit - too_many_ids - 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 example: invalid_input message: type: string description: Human-readable error guidance. example: Invalid input. Check the request body. reason: type: string description: Machine-readable reason for a login cooldown. example: temporary_issue retryAfter: type: integer minimum: 1 description: Seconds until the next permitted request. example: 60 retryAfterMs: type: integer minimum: 1 description: Required wait in milliseconds. example: 60000 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 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 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 example: type: state_change id: '9876543210' state: liked UserIdentityVerification: description: Identity verification metadata displayed by X. type: object properties: description: type: string isIdentityVerified: type: boolean verifiedSinceMsec: type: string 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 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