---
title: "Search tweets by query, Tweet ID, X status URL, or account date window"
method: GET
path: "/api/v1/x/tweets/search"
tags: ["Tweets"]
---

# Search tweets by query, Tweet ID, X status URL, or account date window

`GET /api/v1/x/tweets/search`

No-mode search maximizes coverage.

## Query parameters

- `q` string, required
- `queryType` 'Latest' | 'Top'
- `mode` 'standard' | 'coverage'
- `cursor` string
- `sinceTime` string
- `untilTime` string
- `limit` integer
- `fromUser` string
- `toUser` string
- `mentioning` string
- `language` string
- `sinceDate` string, date
- `untilDate` string, date
- `mediaType` 'images' | 'videos' | 'gifs' | 'media' | 'links' | 'none'
- `minFaves` integer
- `minRetweets` integer
- `minReplies` integer
- `minQuotes` integer
- `minViews` integer
- `minBookmarks` integer
- `maxFaves` integer
- `maxRetweets` integer
- `maxReplies` integer
- `maxQuotes` integer
- `blueVerifiedOnly` boolean
- `cardName` string
- `source` string
- `excludeSource` string
- `geocode` string
- `sinceId` string
- `maxId` string
- `near` string
- `within` string
- `withinTime` string
- `nativeRetweets` boolean
- `safe` boolean
- `news` boolean
- `verifiedOnly` boolean
- `replies` 'include' | 'exclude' | 'only'
- `retweets` 'include' | 'exclude' | 'only'
- `quotes` 'include' | 'exclude' | 'only'
- `exactPhrase` string
- `excludeWords` string
- `anyWords` string
- `hashtags` string
- `cashtags` string
- `url` string
- `conversationId` string
- `inReplyToTweetId` string
- `quotesOfTweetId` string
- `retweetsOfTweetId` string
- `listId` string
- `place` string
- `placeCountry` string
- `pointRadius` string
- `boundingBox` string
- `advancedQuery` string

## Response `200`

Search results

- union
  - PaginatedTweets — 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.
    - `tweets` SearchTweet[], required
      - `id` string, required
      - `text` string, required
      - `type` string
      - `createdAt` string
      - `isNoteTweet` boolean — True for Note Tweets (long-form content, up to 25,000 characters)
      - `isReply` boolean — True when this search result is a reply
      - `isQuoteStatus` boolean — True when this search result quotes another tweet
      - `isLimitedReply` boolean — Whether the tweet has limited reply permissions
      - `inReplyToId` string — ID of the tweet this result replies to.
      - `inReplyToUserId` string — ID of the user this result replies to.
      - `inReplyToUsername` string — Username this result replies to.
      - `conversationId` string — Root tweet ID for the search result conversation
      - `source` string — Client application used to post the tweet
      - `displayTextRange` integer[] — Rendered text's start and end offsets.
      - `contentDisclosure` ContentDisclosure — Content disclosure metadata shown by X when a tweet is labeled as paid partnership content or AI-generated media.
        - `advertising` object
          - `isPaidPromotion` boolean — True when X labels the tweet as paid promotion content.
        - `aiGenerated` object
          - `detectionSource` string — Source of the AI-generated media disclosure.
          - `hasAiGeneratedMedia` boolean — True when X labels the tweet as containing AI-generated media.
      - `article` TweetArticleMetadata — Article metadata attached to a tweet.
        - `id` string
        - `title` string
        - `previewText` string
        - `coverMediaUrl` string
      - `card` TweetCard — Public card metadata attached to a tweet.
        - `id` string
        - `name` string
        - `url` string
        - `bindingValues` object
      - `communityNote` TweetCommunityNote — Community Note presentation metadata returned by X.
        - `id` string
        - `title` string
        - `shortTitle` string
        - `subtitle` string
        - `footer` string
        - `destinationUrl` string
        - `visualStyle` string
      - `edit` TweetEdit — Edit history metadata returned by X.
        - `editTweetIds` string[]
        - `editableUntilMsecs` string
      - `isTranslatable` boolean
      - `noteTweet` TweetNote — Complete Note Tweet content and rich-text metadata.
        - `id` string
        - `text` string, required
        - `isExpandable` boolean
        - `entities` object
        - `richtextTags` object[]
          - `fromIndex` integer, required
          - `toIndex` integer, required
          - `types` string[], required
      - `place` TweetPlace — Public place metadata attached to a tweet.
        - `boundingBox` object
        - `country` string
        - `countryCode` string
        - `fullName` string
        - `id` string
        - `name` string
        - `placeType` string
        - `url` string
      - `possiblySensitive` boolean
      - `previousCounts` TweetPreviousCounts — Engagement counts retained from a prior tweet edit.
        - `bookmarkCount` integer
        - `likeCount` integer
        - `quoteCount` integer
        - `replyCount` integer
        - `retweetCount` integer
      - `viewState` string
      - `entities` object — Parsed search-result entities including URLs, mentions, hashtags, and media markers
      - `quoted_tweet` EmbeddedTweet — 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.
        - `id` string, required
        - `text` string, required
        - `type` string
        - `createdAt` string
        - `url` string
        - `lang` string
        - `retweetCount` integer, required
        - `replyCount` integer, required
        - `likeCount` integer, required
        - `quoteCount` integer, required
        - `viewCount` integer, required
        - `bookmarkCount` integer, required
        - `isReply` boolean
        - `isLimitedReply` boolean
        - `isNoteTweet` boolean
        - `isQuoteStatus` boolean
        - `inReplyToId` string
        - `inReplyToUserId` string
        - `inReplyToUsername` string
        - `conversationId` string
        - `source` string
        - `displayTextRange` integer[]
        - `contentDisclosure` ContentDisclosure — Content disclosure metadata shown by X when a tweet is labeled as paid partnership content or AI-generated media.
          - `advertising` object
            - `isPaidPromotion` boolean — True when X labels the tweet as paid promotion content.
          - `aiGenerated` object
            - `detectionSource` string — Source of the AI-generated media disclosure.
            - `hasAiGeneratedMedia` boolean — True when X labels the tweet as containing AI-generated media.
        - `article` TweetArticleMetadata — Article metadata attached to a tweet.
          - `id` string
          - `title` string
          - `previewText` string
          - `coverMediaUrl` string
        - `card` TweetCard — Public card metadata attached to a tweet.
          - `id` string
          - `name` string
          - `url` string
          - `bindingValues` object
        - `communityNote` TweetCommunityNote — Community Note presentation metadata returned by X.
          - `id` string
          - `title` string
          - `shortTitle` string
          - `subtitle` string
          - `footer` string
          - `destinationUrl` string
          - `visualStyle` string
        - `edit` TweetEdit — Edit history metadata returned by X.
          - `editTweetIds` string[]
          - `editableUntilMsecs` string
        - `isTranslatable` boolean
        - `noteTweet` TweetNote — Complete Note Tweet content and rich-text metadata.
          - `id` string
          - `text` string, required
          - `isExpandable` boolean
          - `entities` object
          - `richtextTags` object[]
            - `fromIndex` integer, required
            - `toIndex` integer, required
            - `types` string[], required
        - `place` TweetPlace — Public place metadata attached to a tweet.
          - `boundingBox` object
          - `country` string
          - `countryCode` string
          - `fullName` string
          - `id` string
          - `name` string
          - `placeType` string
          - `url` string
        - `possiblySensitive` boolean
        - `previousCounts` TweetPreviousCounts — Engagement counts retained from a prior tweet edit.
          - `bookmarkCount` integer
          - `likeCount` integer
          - `quoteCount` integer
          - `replyCount` integer
          - `retweetCount` integer
        - `viewState` string
        - `entities` object
        - `quoted_tweet` EmbeddedTweet — recursive
        - `retweeted_tweet` EmbeddedTweet — recursive
        - `media` TweetMedia[]
          - `mediaUrl` string, required — Media preview URL
          - `type` 'photo' | 'video' | 'animated_gif', required
          - `url` string, required — X media link from the tweet
          - `allowDownload` boolean — Whether X permits direct media download.
          - `altText` string — Accessibility text supplied for the media.
          - `aspectRatio` integer[] — Video aspect ratio as width and height.
          - `availabilityStatus` string — Media availability state reported by X.
          - `displayUrl` string — Display-friendly media URL reported by X.
          - `durationMillis` integer — Video duration in milliseconds.
          - `expandedUrl` string — Expanded X media URL.
          - `faceRects` object — Face-aware crop rectangles grouped by media size.
          - `focusRects` object[] — Suggested image crops reported by X.
            - `x` integer, required
            - `y` integer, required
            - `w` integer, required
            - `h` integer, required
          - `height` integer — Original media height.
          - `id` string — X media entity ID.
          - `indices` integer[] — Media entity offsets in the tweet text.
          - `mediaKey` string — Stable X media key.
          - `monetizable` boolean — Whether X reports the media as monetizable.
          - `sizes` object — Named media renditions and resize modes.
          - `videoVariants` object[] — Available video encodings, ordered as returned
            - `bitrate` integer
            - `contentType` string, required
            - `url` string, required
          - `width` integer — Original media width.
        - `author` UserProfile — X user profile with bio, follower counts, and verification status.
          - `id` string, required
          - `username` string, required
          - `name` string, required
          - `description` string
          - `followers` integer
          - `following` integer
          - `verified` boolean
          - `isBlueVerified` boolean — Whether X shows a blue verification badge
          - `isVerified` boolean — Whether X marks the profile as verified
          - `profilePicture` string
          - `coverPicture` string
          - `profileBannerUrl` string — Original X profile banner field when available
          - `location` string
          - `createdAt` string
          - `statusesCount` integer
          - `mediaCount` integer
          - `protected` boolean — Whether the profile protects its posts
          - `url` string
          - `favouritesCount` integer
          - `hasCustomTimelines` boolean
          - `isTranslator` boolean
          - `withheldInCountries` string[]
          - `possiblySensitive` boolean
          - `pinnedTweetIds` string[]
          - `isAutomated` boolean
          - `automatedBy` string
          - `unavailable` boolean
          - `unavailableReason` string
          - `verifiedType` string
          - `affiliatesHighlightedLabel` UserAffiliateLabel — Organization affiliation label shown on an X profile.
            - `badgeUrl` string
            - `description` string
            - `url` string
            - `urlType` string
            - `userLabelDisplayType` string
            - `userLabelType` string
          - `businessAccountAffiliatesCount` integer
          - `creatorSubscriptionsCount` integer
          - `hasGraduatedAccess` boolean
          - `hasHiddenSubscriptionsOnProfile` boolean
          - `highlightsInfo` UserHighlightsInfo — Profile highlight availability and count metadata.
            - `canHighlightTweets` boolean
            - `highlightedTweets` string
          - `identityVerification` UserIdentityVerification — Identity verification metadata displayed by X.
            - `description` string
            - `isIdentityVerified` boolean
            - `verifiedSinceMsec` string
          - `isProfileTranslatable` boolean
          - `parodyCommentaryFanLabel` string
          - `profileDescriptionLanguage` string
          - `profileImageShape` string
          - `profileInterstitialType` string
          - `profileSortEnabled` boolean
          - `profileTranslatorType` string
          - `superFollowEligible` boolean
          - `communityRole` string — Community role when returned by community member reads
          - `profile_bio` object — Structured profile bio with entity annotations
      - `retweeted_tweet` EmbeddedTweet — 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.
        - `id` string, required
        - `text` string, required
        - `type` string
        - `createdAt` string
        - `url` string
        - `lang` string
        - `retweetCount` integer, required
        - `replyCount` integer, required
        - `likeCount` integer, required
        - `quoteCount` integer, required
        - `viewCount` integer, required
        - `bookmarkCount` integer, required
        - `isReply` boolean
        - `isLimitedReply` boolean
        - `isNoteTweet` boolean
        - `isQuoteStatus` boolean
        - `inReplyToId` string
        - `inReplyToUserId` string
        - `inReplyToUsername` string
        - `conversationId` string
        - `source` string
        - `displayTextRange` integer[]
        - `contentDisclosure` ContentDisclosure — Content disclosure metadata shown by X when a tweet is labeled as paid partnership content or AI-generated media.
          - `advertising` object
            - `isPaidPromotion` boolean — True when X labels the tweet as paid promotion content.
          - `aiGenerated` object
            - `detectionSource` string — Source of the AI-generated media disclosure.
            - `hasAiGeneratedMedia` boolean — True when X labels the tweet as containing AI-generated media.
        - `article` TweetArticleMetadata — Article metadata attached to a tweet.
          - `id` string
          - `title` string
          - `previewText` string
          - `coverMediaUrl` string
        - `card` TweetCard — Public card metadata attached to a tweet.
          - `id` string
          - `name` string
          - `url` string
          - `bindingValues` object
        - `communityNote` TweetCommunityNote — Community Note presentation metadata returned by X.
          - `id` string
          - `title` string
          - `shortTitle` string
          - `subtitle` string
          - `footer` string
          - `destinationUrl` string
          - `visualStyle` string
        - `edit` TweetEdit — Edit history metadata returned by X.
          - `editTweetIds` string[]
          - `editableUntilMsecs` string
        - `isTranslatable` boolean
        - `noteTweet` TweetNote — Complete Note Tweet content and rich-text metadata.
          - `id` string
          - `text` string, required
          - `isExpandable` boolean
          - `entities` object
          - `richtextTags` object[]
            - `fromIndex` integer, required
            - `toIndex` integer, required
            - `types` string[], required
        - `place` TweetPlace — Public place metadata attached to a tweet.
          - `boundingBox` object
          - `country` string
          - `countryCode` string
          - `fullName` string
          - `id` string
          - `name` string
          - `placeType` string
          - `url` string
        - `possiblySensitive` boolean
        - `previousCounts` TweetPreviousCounts — Engagement counts retained from a prior tweet edit.
          - `bookmarkCount` integer
          - `likeCount` integer
          - `quoteCount` integer
          - `replyCount` integer
          - `retweetCount` integer
        - `viewState` string
        - `entities` object
        - `quoted_tweet` EmbeddedTweet — recursive
        - `retweeted_tweet` EmbeddedTweet — recursive
        - `media` TweetMedia[]
          - `mediaUrl` string, required — Media preview URL
          - `type` 'photo' | 'video' | 'animated_gif', required
          - `url` string, required — X media link from the tweet
          - `allowDownload` boolean — Whether X permits direct media download.
          - `altText` string — Accessibility text supplied for the media.
          - `aspectRatio` integer[] — Video aspect ratio as width and height.
          - `availabilityStatus` string — Media availability state reported by X.
          - `displayUrl` string — Display-friendly media URL reported by X.
          - `durationMillis` integer — Video duration in milliseconds.
          - `expandedUrl` string — Expanded X media URL.
          - `faceRects` object — Face-aware crop rectangles grouped by media size.
          - `focusRects` object[] — Suggested image crops reported by X.
            - `x` integer, required
            - `y` integer, required
            - `w` integer, required
            - `h` integer, required
          - `height` integer — Original media height.
          - `id` string — X media entity ID.
          - `indices` integer[] — Media entity offsets in the tweet text.
          - `mediaKey` string — Stable X media key.
          - `monetizable` boolean — Whether X reports the media as monetizable.
          - `sizes` object — Named media renditions and resize modes.
          - `videoVariants` object[] — Available video encodings, ordered as returned
            - `bitrate` integer
            - `contentType` string, required
            - `url` string, required
          - `width` integer — Original media width.
        - `author` UserProfile — X user profile with bio, follower counts, and verification status.
          - `id` string, required
          - `username` string, required
          - `name` string, required
          - `description` string
          - `followers` integer
          - `following` integer
          - `verified` boolean
          - `isBlueVerified` boolean — Whether X shows a blue verification badge
          - `isVerified` boolean — Whether X marks the profile as verified
          - `profilePicture` string
          - `coverPicture` string
          - `profileBannerUrl` string — Original X profile banner field when available
          - `location` string
          - `createdAt` string
          - `statusesCount` integer
          - `mediaCount` integer
          - `protected` boolean — Whether the profile protects its posts
          - `url` string
          - `favouritesCount` integer
          - `hasCustomTimelines` boolean
          - `isTranslator` boolean
          - `withheldInCountries` string[]
          - `possiblySensitive` boolean
          - `pinnedTweetIds` string[]
          - `isAutomated` boolean
          - `automatedBy` string
          - `unavailable` boolean
          - `unavailableReason` string
          - `verifiedType` string
          - `affiliatesHighlightedLabel` UserAffiliateLabel — Organization affiliation label shown on an X profile.
            - `badgeUrl` string
            - `description` string
            - `url` string
            - `urlType` string
            - `userLabelDisplayType` string
            - `userLabelType` string
          - `businessAccountAffiliatesCount` integer
          - `creatorSubscriptionsCount` integer
          - `hasGraduatedAccess` boolean
          - `hasHiddenSubscriptionsOnProfile` boolean
          - `highlightsInfo` UserHighlightsInfo — Profile highlight availability and count metadata.
            - `canHighlightTweets` boolean
            - `highlightedTweets` string
          - `identityVerification` UserIdentityVerification — Identity verification metadata displayed by X.
            - `description` string
            - `isIdentityVerified` boolean
            - `verifiedSinceMsec` string
          - `isProfileTranslatable` boolean
          - `parodyCommentaryFanLabel` string
          - `profileDescriptionLanguage` string
          - `profileImageShape` string
          - `profileInterstitialType` string
          - `profileSortEnabled` boolean
          - `profileTranslatorType` string
          - `superFollowEligible` boolean
          - `communityRole` string — Community role when returned by community member reads
          - `profile_bio` object — Structured profile bio with entity annotations
      - `media` TweetMedia[] — Search-result media attachments, omitted when no media is present
        - `mediaUrl` string, required — Media preview URL
        - `type` 'photo' | 'video' | 'animated_gif', required
        - `url` string, required — X media link from the tweet
        - `allowDownload` boolean — Whether X permits direct media download.
        - `altText` string — Accessibility text supplied for the media.
        - `aspectRatio` integer[] — Video aspect ratio as width and height.
        - `availabilityStatus` string — Media availability state reported by X.
        - `displayUrl` string — Display-friendly media URL reported by X.
        - `durationMillis` integer — Video duration in milliseconds.
        - `expandedUrl` string — Expanded X media URL.
        - `faceRects` object — Face-aware crop rectangles grouped by media size.
        - `focusRects` object[] — Suggested image crops reported by X.
          - `x` integer, required
          - `y` integer, required
          - `w` integer, required
          - `h` integer, required
        - `height` integer — Original media height.
        - `id` string — X media entity ID.
        - `indices` integer[] — Media entity offsets in the tweet text.
        - `mediaKey` string — Stable X media key.
        - `monetizable` boolean — Whether X reports the media as monetizable.
        - `sizes` object — Named media renditions and resize modes.
        - `videoVariants` object[] — Available video encodings, ordered as returned
          - `bitrate` integer
          - `contentType` string, required
          - `url` string, required
        - `width` integer — Original media width.
      - `url` string — Search result permalink.
      - `lang` string — Search result language code.
      - `likeCount` integer, required
      - `retweetCount` integer, required
      - `replyCount` integer, required
      - `quoteCount` integer, required
      - `viewCount` integer, required
      - `bookmarkCount` integer, required
      - `author` UserProfile — X user profile with bio, follower counts, and verification status.
        - `id` string, required
        - `username` string, required
        - `name` string, required
        - `description` string
        - `followers` integer
        - `following` integer
        - `verified` boolean
        - `isBlueVerified` boolean — Whether X shows a blue verification badge
        - `isVerified` boolean — Whether X marks the profile as verified
        - `profilePicture` string
        - `coverPicture` string
        - `profileBannerUrl` string — Original X profile banner field when available
        - `location` string
        - `createdAt` string
        - `statusesCount` integer
        - `mediaCount` integer
        - `protected` boolean — Whether the profile protects its posts
        - `url` string
        - `favouritesCount` integer
        - `hasCustomTimelines` boolean
        - `isTranslator` boolean
        - `withheldInCountries` string[]
        - `possiblySensitive` boolean
        - `pinnedTweetIds` string[]
        - `isAutomated` boolean
        - `automatedBy` string
        - `unavailable` boolean
        - `unavailableReason` string
        - `verifiedType` string
        - `affiliatesHighlightedLabel` UserAffiliateLabel — Organization affiliation label shown on an X profile.
          - `badgeUrl` string
          - `description` string
          - `url` string
          - `urlType` string
          - `userLabelDisplayType` string
          - `userLabelType` string
        - `businessAccountAffiliatesCount` integer
        - `creatorSubscriptionsCount` integer
        - `hasGraduatedAccess` boolean
        - `hasHiddenSubscriptionsOnProfile` boolean
        - `highlightsInfo` UserHighlightsInfo — Profile highlight availability and count metadata.
          - `canHighlightTweets` boolean
          - `highlightedTweets` string
        - `identityVerification` UserIdentityVerification — Identity verification metadata displayed by X.
          - `description` string
          - `isIdentityVerified` boolean
          - `verifiedSinceMsec` string
        - `isProfileTranslatable` boolean
        - `parodyCommentaryFanLabel` string
        - `profileDescriptionLanguage` string
        - `profileImageShape` string
        - `profileInterstitialType` string
        - `profileSortEnabled` boolean
        - `profileTranslatorType` string
        - `superFollowEligible` boolean
        - `communityRole` string — Community role when returned by community member reads
        - `profile_bio` object — Structured profile bio with entity annotations
    - `has_next_page` boolean, required
    - `next_cursor` string, required
  - TweetSearchCoverageResponse — 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.
    - `tweets` SearchTweet[], required
      - `id` string, required
      - `text` string, required
      - `type` string
      - `createdAt` string
      - `isNoteTweet` boolean — True for Note Tweets (long-form content, up to 25,000 characters)
      - `isReply` boolean — True when this search result is a reply
      - `isQuoteStatus` boolean — True when this search result quotes another tweet
      - `isLimitedReply` boolean — Whether the tweet has limited reply permissions
      - `inReplyToId` string — ID of the tweet this result replies to.
      - `inReplyToUserId` string — ID of the user this result replies to.
      - `inReplyToUsername` string — Username this result replies to.
      - `conversationId` string — Root tweet ID for the search result conversation
      - `source` string — Client application used to post the tweet
      - `displayTextRange` integer[] — Rendered text's start and end offsets.
      - `contentDisclosure` ContentDisclosure — Content disclosure metadata shown by X when a tweet is labeled as paid partnership content or AI-generated media.
        - `advertising` object
          - `isPaidPromotion` boolean — True when X labels the tweet as paid promotion content.
        - `aiGenerated` object
          - `detectionSource` string — Source of the AI-generated media disclosure.
          - `hasAiGeneratedMedia` boolean — True when X labels the tweet as containing AI-generated media.
      - `article` TweetArticleMetadata — Article metadata attached to a tweet.
        - `id` string
        - `title` string
        - `previewText` string
        - `coverMediaUrl` string
      - `card` TweetCard — Public card metadata attached to a tweet.
        - `id` string
        - `name` string
        - `url` string
        - `bindingValues` object
      - `communityNote` TweetCommunityNote — Community Note presentation metadata returned by X.
        - `id` string
        - `title` string
        - `shortTitle` string
        - `subtitle` string
        - `footer` string
        - `destinationUrl` string
        - `visualStyle` string
      - `edit` TweetEdit — Edit history metadata returned by X.
        - `editTweetIds` string[]
        - `editableUntilMsecs` string
      - `isTranslatable` boolean
      - `noteTweet` TweetNote — Complete Note Tweet content and rich-text metadata.
        - `id` string
        - `text` string, required
        - `isExpandable` boolean
        - `entities` object
        - `richtextTags` object[]
          - `fromIndex` integer, required
          - `toIndex` integer, required
          - `types` string[], required
      - `place` TweetPlace — Public place metadata attached to a tweet.
        - `boundingBox` object
        - `country` string
        - `countryCode` string
        - `fullName` string
        - `id` string
        - `name` string
        - `placeType` string
        - `url` string
      - `possiblySensitive` boolean
      - `previousCounts` TweetPreviousCounts — Engagement counts retained from a prior tweet edit.
        - `bookmarkCount` integer
        - `likeCount` integer
        - `quoteCount` integer
        - `replyCount` integer
        - `retweetCount` integer
      - `viewState` string
      - `entities` object — Parsed search-result entities including URLs, mentions, hashtags, and media markers
      - `quoted_tweet` EmbeddedTweet — 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.
        - `id` string, required
        - `text` string, required
        - `type` string
        - `createdAt` string
        - `url` string
        - `lang` string
        - `retweetCount` integer, required
        - `replyCount` integer, required
        - `likeCount` integer, required
        - `quoteCount` integer, required
        - `viewCount` integer, required
        - `bookmarkCount` integer, required
        - `isReply` boolean
        - `isLimitedReply` boolean
        - `isNoteTweet` boolean
        - `isQuoteStatus` boolean
        - `inReplyToId` string
        - `inReplyToUserId` string
        - `inReplyToUsername` string
        - `conversationId` string
        - `source` string
        - `displayTextRange` integer[]
        - `contentDisclosure` ContentDisclosure — Content disclosure metadata shown by X when a tweet is labeled as paid partnership content or AI-generated media.
          - `advertising` object
            - `isPaidPromotion` boolean — True when X labels the tweet as paid promotion content.
          - `aiGenerated` object
            - `detectionSource` string — Source of the AI-generated media disclosure.
            - `hasAiGeneratedMedia` boolean — True when X labels the tweet as containing AI-generated media.
        - `article` TweetArticleMetadata — Article metadata attached to a tweet.
          - `id` string
          - `title` string
          - `previewText` string
          - `coverMediaUrl` string
        - `card` TweetCard — Public card metadata attached to a tweet.
          - `id` string
          - `name` string
          - `url` string
          - `bindingValues` object
        - `communityNote` TweetCommunityNote — Community Note presentation metadata returned by X.
          - `id` string
          - `title` string
          - `shortTitle` string
          - `subtitle` string
          - `footer` string
          - `destinationUrl` string
          - `visualStyle` string
        - `edit` TweetEdit — Edit history metadata returned by X.
          - `editTweetIds` string[]
          - `editableUntilMsecs` string
        - `isTranslatable` boolean
        - `noteTweet` TweetNote — Complete Note Tweet content and rich-text metadata.
          - `id` string
          - `text` string, required
          - `isExpandable` boolean
          - `entities` object
          - `richtextTags` object[]
            - `fromIndex` integer, required
            - `toIndex` integer, required
            - `types` string[], required
        - `place` TweetPlace — Public place metadata attached to a tweet.
          - `boundingBox` object
          - `country` string
          - `countryCode` string
          - `fullName` string
          - `id` string
          - `name` string
          - `placeType` string
          - `url` string
        - `possiblySensitive` boolean
        - `previousCounts` TweetPreviousCounts — Engagement counts retained from a prior tweet edit.
          - `bookmarkCount` integer
          - `likeCount` integer
          - `quoteCount` integer
          - `replyCount` integer
          - `retweetCount` integer
        - `viewState` string
        - `entities` object
        - `quoted_tweet` EmbeddedTweet — recursive
        - `retweeted_tweet` EmbeddedTweet — recursive
        - `media` TweetMedia[]
          - `mediaUrl` string, required — Media preview URL
          - `type` 'photo' | 'video' | 'animated_gif', required
          - `url` string, required — X media link from the tweet
          - `allowDownload` boolean — Whether X permits direct media download.
          - `altText` string — Accessibility text supplied for the media.
          - `aspectRatio` integer[] — Video aspect ratio as width and height.
          - `availabilityStatus` string — Media availability state reported by X.
          - `displayUrl` string — Display-friendly media URL reported by X.
          - `durationMillis` integer — Video duration in milliseconds.
          - `expandedUrl` string — Expanded X media URL.
          - `faceRects` object — Face-aware crop rectangles grouped by media size.
          - `focusRects` object[] — Suggested image crops reported by X.
            - `x` integer, required
            - `y` integer, required
            - `w` integer, required
            - `h` integer, required
          - `height` integer — Original media height.
          - `id` string — X media entity ID.
          - `indices` integer[] — Media entity offsets in the tweet text.
          - `mediaKey` string — Stable X media key.
          - `monetizable` boolean — Whether X reports the media as monetizable.
          - `sizes` object — Named media renditions and resize modes.
          - `videoVariants` object[] — Available video encodings, ordered as returned
            - `bitrate` integer
            - `contentType` string, required
            - `url` string, required
          - `width` integer — Original media width.
        - `author` UserProfile — X user profile with bio, follower counts, and verification status.
          - `id` string, required
          - `username` string, required
          - `name` string, required
          - `description` string
          - `followers` integer
          - `following` integer
          - `verified` boolean
          - `isBlueVerified` boolean — Whether X shows a blue verification badge
          - `isVerified` boolean — Whether X marks the profile as verified
          - `profilePicture` string
          - `coverPicture` string
          - `profileBannerUrl` string — Original X profile banner field when available
          - `location` string
          - `createdAt` string
          - `statusesCount` integer
          - `mediaCount` integer
          - `protected` boolean — Whether the profile protects its posts
          - `url` string
          - `favouritesCount` integer
          - `hasCustomTimelines` boolean
          - `isTranslator` boolean
          - `withheldInCountries` string[]
          - `possiblySensitive` boolean
          - `pinnedTweetIds` string[]
          - `isAutomated` boolean
          - `automatedBy` string
          - `unavailable` boolean
          - `unavailableReason` string
          - `verifiedType` string
          - `affiliatesHighlightedLabel` UserAffiliateLabel — Organization affiliation label shown on an X profile.
            - `badgeUrl` string
            - `description` string
            - `url` string
            - `urlType` string
            - `userLabelDisplayType` string
            - `userLabelType` string
          - `businessAccountAffiliatesCount` integer
          - `creatorSubscriptionsCount` integer
          - `hasGraduatedAccess` boolean
          - `hasHiddenSubscriptionsOnProfile` boolean
          - `highlightsInfo` UserHighlightsInfo — Profile highlight availability and count metadata.
            - `canHighlightTweets` boolean
            - `highlightedTweets` string
          - `identityVerification` UserIdentityVerification — Identity verification metadata displayed by X.
            - `description` string
            - `isIdentityVerified` boolean
            - `verifiedSinceMsec` string
          - `isProfileTranslatable` boolean
          - `parodyCommentaryFanLabel` string
          - `profileDescriptionLanguage` string
          - `profileImageShape` string
          - `profileInterstitialType` string
          - `profileSortEnabled` boolean
          - `profileTranslatorType` string
          - `superFollowEligible` boolean
          - `communityRole` string — Community role when returned by community member reads
          - `profile_bio` object — Structured profile bio with entity annotations
      - `retweeted_tweet` EmbeddedTweet — 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.
        - `id` string, required
        - `text` string, required
        - `type` string
        - `createdAt` string
        - `url` string
        - `lang` string
        - `retweetCount` integer, required
        - `replyCount` integer, required
        - `likeCount` integer, required
        - `quoteCount` integer, required
        - `viewCount` integer, required
        - `bookmarkCount` integer, required
        - `isReply` boolean
        - `isLimitedReply` boolean
        - `isNoteTweet` boolean
        - `isQuoteStatus` boolean
        - `inReplyToId` string
        - `inReplyToUserId` string
        - `inReplyToUsername` string
        - `conversationId` string
        - `source` string
        - `displayTextRange` integer[]
        - `contentDisclosure` ContentDisclosure — Content disclosure metadata shown by X when a tweet is labeled as paid partnership content or AI-generated media.
          - `advertising` object
            - `isPaidPromotion` boolean — True when X labels the tweet as paid promotion content.
          - `aiGenerated` object
            - `detectionSource` string — Source of the AI-generated media disclosure.
            - `hasAiGeneratedMedia` boolean — True when X labels the tweet as containing AI-generated media.
        - `article` TweetArticleMetadata — Article metadata attached to a tweet.
          - `id` string
          - `title` string
          - `previewText` string
          - `coverMediaUrl` string
        - `card` TweetCard — Public card metadata attached to a tweet.
          - `id` string
          - `name` string
          - `url` string
          - `bindingValues` object
        - `communityNote` TweetCommunityNote — Community Note presentation metadata returned by X.
          - `id` string
          - `title` string
          - `shortTitle` string
          - `subtitle` string
          - `footer` string
          - `destinationUrl` string
          - `visualStyle` string
        - `edit` TweetEdit — Edit history metadata returned by X.
          - `editTweetIds` string[]
          - `editableUntilMsecs` string
        - `isTranslatable` boolean
        - `noteTweet` TweetNote — Complete Note Tweet content and rich-text metadata.
          - `id` string
          - `text` string, required
          - `isExpandable` boolean
          - `entities` object
          - `richtextTags` object[]
            - `fromIndex` integer, required
            - `toIndex` integer, required
            - `types` string[], required
        - `place` TweetPlace — Public place metadata attached to a tweet.
          - `boundingBox` object
          - `country` string
          - `countryCode` string
          - `fullName` string
          - `id` string
          - `name` string
          - `placeType` string
          - `url` string
        - `possiblySensitive` boolean
        - `previousCounts` TweetPreviousCounts — Engagement counts retained from a prior tweet edit.
          - `bookmarkCount` integer
          - `likeCount` integer
          - `quoteCount` integer
          - `replyCount` integer
          - `retweetCount` integer
        - `viewState` string
        - `entities` object
        - `quoted_tweet` EmbeddedTweet — recursive
        - `retweeted_tweet` EmbeddedTweet — recursive
        - `media` TweetMedia[]
          - `mediaUrl` string, required — Media preview URL
          - `type` 'photo' | 'video' | 'animated_gif', required
          - `url` string, required — X media link from the tweet
          - `allowDownload` boolean — Whether X permits direct media download.
          - `altText` string — Accessibility text supplied for the media.
          - `aspectRatio` integer[] — Video aspect ratio as width and height.
          - `availabilityStatus` string — Media availability state reported by X.
          - `displayUrl` string — Display-friendly media URL reported by X.
          - `durationMillis` integer — Video duration in milliseconds.
          - `expandedUrl` string — Expanded X media URL.
          - `faceRects` object — Face-aware crop rectangles grouped by media size.
          - `focusRects` object[] — Suggested image crops reported by X.
            - `x` integer, required
            - `y` integer, required
            - `w` integer, required
            - `h` integer, required
          - `height` integer — Original media height.
          - `id` string — X media entity ID.
          - `indices` integer[] — Media entity offsets in the tweet text.
          - `mediaKey` string — Stable X media key.
          - `monetizable` boolean — Whether X reports the media as monetizable.
          - `sizes` object — Named media renditions and resize modes.
          - `videoVariants` object[] — Available video encodings, ordered as returned
            - `bitrate` integer
            - `contentType` string, required
            - `url` string, required
          - `width` integer — Original media width.
        - `author` UserProfile — X user profile with bio, follower counts, and verification status.
          - `id` string, required
          - `username` string, required
          - `name` string, required
          - `description` string
          - `followers` integer
          - `following` integer
          - `verified` boolean
          - `isBlueVerified` boolean — Whether X shows a blue verification badge
          - `isVerified` boolean — Whether X marks the profile as verified
          - `profilePicture` string
          - `coverPicture` string
          - `profileBannerUrl` string — Original X profile banner field when available
          - `location` string
          - `createdAt` string
          - `statusesCount` integer
          - `mediaCount` integer
          - `protected` boolean — Whether the profile protects its posts
          - `url` string
          - `favouritesCount` integer
          - `hasCustomTimelines` boolean
          - `isTranslator` boolean
          - `withheldInCountries` string[]
          - `possiblySensitive` boolean
          - `pinnedTweetIds` string[]
          - `isAutomated` boolean
          - `automatedBy` string
          - `unavailable` boolean
          - `unavailableReason` string
          - `verifiedType` string
          - `affiliatesHighlightedLabel` UserAffiliateLabel — Organization affiliation label shown on an X profile.
            - `badgeUrl` string
            - `description` string
            - `url` string
            - `urlType` string
            - `userLabelDisplayType` string
            - `userLabelType` string
          - `businessAccountAffiliatesCount` integer
          - `creatorSubscriptionsCount` integer
          - `hasGraduatedAccess` boolean
          - `hasHiddenSubscriptionsOnProfile` boolean
          - `highlightsInfo` UserHighlightsInfo — Profile highlight availability and count metadata.
            - `canHighlightTweets` boolean
            - `highlightedTweets` string
          - `identityVerification` UserIdentityVerification — Identity verification metadata displayed by X.
            - `description` string
            - `isIdentityVerified` boolean
            - `verifiedSinceMsec` string
          - `isProfileTranslatable` boolean
          - `parodyCommentaryFanLabel` string
          - `profileDescriptionLanguage` string
          - `profileImageShape` string
          - `profileInterstitialType` string
          - `profileSortEnabled` boolean
          - `profileTranslatorType` string
          - `superFollowEligible` boolean
          - `communityRole` string — Community role when returned by community member reads
          - `profile_bio` object — Structured profile bio with entity annotations
      - `media` TweetMedia[] — Search-result media attachments, omitted when no media is present
        - `mediaUrl` string, required — Media preview URL
        - `type` 'photo' | 'video' | 'animated_gif', required
        - `url` string, required — X media link from the tweet
        - `allowDownload` boolean — Whether X permits direct media download.
        - `altText` string — Accessibility text supplied for the media.
        - `aspectRatio` integer[] — Video aspect ratio as width and height.
        - `availabilityStatus` string — Media availability state reported by X.
        - `displayUrl` string — Display-friendly media URL reported by X.
        - `durationMillis` integer — Video duration in milliseconds.
        - `expandedUrl` string — Expanded X media URL.
        - `faceRects` object — Face-aware crop rectangles grouped by media size.
        - `focusRects` object[] — Suggested image crops reported by X.
          - `x` integer, required
          - `y` integer, required
          - `w` integer, required
          - `h` integer, required
        - `height` integer — Original media height.
        - `id` string — X media entity ID.
        - `indices` integer[] — Media entity offsets in the tweet text.
        - `mediaKey` string — Stable X media key.
        - `monetizable` boolean — Whether X reports the media as monetizable.
        - `sizes` object — Named media renditions and resize modes.
        - `videoVariants` object[] — Available video encodings, ordered as returned
          - `bitrate` integer
          - `contentType` string, required
          - `url` string, required
        - `width` integer — Original media width.
      - `url` string — Search result permalink.
      - `lang` string — Search result language code.
      - `likeCount` integer, required
      - `retweetCount` integer, required
      - `replyCount` integer, required
      - `quoteCount` integer, required
      - `viewCount` integer, required
      - `bookmarkCount` integer, required
      - `author` UserProfile — X user profile with bio, follower counts, and verification status.
        - `id` string, required
        - `username` string, required
        - `name` string, required
        - `description` string
        - `followers` integer
        - `following` integer
        - `verified` boolean
        - `isBlueVerified` boolean — Whether X shows a blue verification badge
        - `isVerified` boolean — Whether X marks the profile as verified
        - `profilePicture` string
        - `coverPicture` string
        - `profileBannerUrl` string — Original X profile banner field when available
        - `location` string
        - `createdAt` string
        - `statusesCount` integer
        - `mediaCount` integer
        - `protected` boolean — Whether the profile protects its posts
        - `url` string
        - `favouritesCount` integer
        - `hasCustomTimelines` boolean
        - `isTranslator` boolean
        - `withheldInCountries` string[]
        - `possiblySensitive` boolean
        - `pinnedTweetIds` string[]
        - `isAutomated` boolean
        - `automatedBy` string
        - `unavailable` boolean
        - `unavailableReason` string
        - `verifiedType` string
        - `affiliatesHighlightedLabel` UserAffiliateLabel — Organization affiliation label shown on an X profile.
          - `badgeUrl` string
          - `description` string
          - `url` string
          - `urlType` string
          - `userLabelDisplayType` string
          - `userLabelType` string
        - `businessAccountAffiliatesCount` integer
        - `creatorSubscriptionsCount` integer
        - `hasGraduatedAccess` boolean
        - `hasHiddenSubscriptionsOnProfile` boolean
        - `highlightsInfo` UserHighlightsInfo — Profile highlight availability and count metadata.
          - `canHighlightTweets` boolean
          - `highlightedTweets` string
        - `identityVerification` UserIdentityVerification — Identity verification metadata displayed by X.
          - `description` string
          - `isIdentityVerified` boolean
          - `verifiedSinceMsec` string
        - `isProfileTranslatable` boolean
        - `parodyCommentaryFanLabel` string
        - `profileDescriptionLanguage` string
        - `profileImageShape` string
        - `profileInterstitialType` string
        - `profileSortEnabled` boolean
        - `profileTranslatorType` string
        - `superFollowEligible` boolean
        - `communityRole` string — Community role when returned by community member reads
        - `profile_bio` object — Structured profile bio with entity annotations
    - `has_next_page` false, required
    - `next_cursor` '', required
    - `diagnostic` TweetSearchCoverageDiagnostic, required — Coverage evidence across parallel search strategies.
      - `complete` boolean, required — True when every strategy exhausted its source.
      - `cursorFailureCount` integer, required
      - `deadlineReached` boolean, required
      - `duplicateCount` integer, required
      - `failedStrategyCount` integer, required
      - `malformedCount` integer, required
      - `pagesFetched` integer, required
      - `partitioned` boolean, required — Whether bounded time windows ran in parallel.
      - `responseTruncated` boolean, required — Whether credits or the requested limit reduced output.
      - `resultLimitReached` boolean, required
      - `returnedTweets` integer, required
      - `stalledStrategyCount` integer, required
      - `strategies` TweetSearchCoverageStrategy[], required
        - `duplicateCount` integer, required
        - `pagesFetched` integer, required
        - `queryType` 'Latest' | 'Top', required
        - `stopReason` 'cursor_failure' | 'deadline' | 'exhausted' | 'failed' | 'page_limit' | 'result_limit' | 'stalled', required
        - `strategy` integer, required
        - `uniqueAdded` integer, required
        - `window` TweetSearchCoverageWindow — Non-overlapping time partition used by one strategy.
          - `sinceTime` string, date-time, required
          - `untilTime` string, date-time, required
      - `strategyCount` integer, required
      - `uniqueTweets` integer, required

## Other responses

- `400` — Missing query
- `401` — 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.
- `402` — 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.
- `409` — Automatic coverage cursor expired or is already in use.
- `424` — Dependency unavailable, unauthorized, or rate limited. Default v1 returns 502. The best-practice response contract returns 424 for transparent dependency failures.
- `429` — Xquik tier rate limit exceeded. The response includes a `Retry-After` header with the number of seconds to wait before retrying.
- `502` — Dependency unavailable, unauthorized, or rate limited. Default v1 returns 502. The best-practice response contract returns 424 for transparent dependency failures.
- `503` — Automatic or explicit maximum coverage is temporarily busy.
- `default` — Unexpected error.

---

[API](https://skmtc.net/xquik-dev/apis/xquik-api-2.md) · [All operations](https://skmtc.net/xquik-dev/apis/xquik-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/xquik-dev/xquik-api-2/versions/c367e6e8f845/schema)