twexapi-io Tweet Engagement Endpoints API

openapi: 3.2.0
info:
  title: TwexAPI REST Tweet Engagement Endpoints API
  description: 'TwexAPI exposes a REST API at `https://api.twexapi.io` for X/Twitter search, profiles, followers, posting, DMs, and agent integrations.


    **Capabilities include:**


    * **Search** — Advanced search, hashtags, cashtags

    * **Tweets** — Post, like, retweet, quote, bookmark, delete

    * **Users** — Batch user information retrieval

    * **Influencers** — Get tweets from top influencers


    All endpoints return a consistent envelope with `code`, `msg`, and `data` fields. See Error Handling for status codes and recovery.


    ## Authentication


    Send your API key on every request:


    ```txt

    Authorization: Bearer YOUR_API_KEY

    ```


    Write actions also require a Twitter cookie or `auth_token`. See Authentication for setup examples.'
  contact:
    name: TwexAPI Support
    email: support@twexapi.io
  license:
    name: MIT
  version: 1.0.0
servers:
- url: https://api.twexapi.io
  description: Development server
tags:
- name: Tweet Engagement Endpoints
paths:
  /twitter/tweets/retweeters/page:
    post:
      tags:
      - Tweet Engagement Endpoints
      summary: Get Retweeters by Page
      description: Retrieve retweeters using cursor-based pagination. Each page returns up to 20 users. Pass next_cursor from the previous response to continue.
      operationId: get_retweeters_page_endpoint_twitter_tweets_retweeters_page_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetRetweetersCursorQuery'
        required: true
      responses:
        '200':
          description: Current page data (up to 20 users) and pagination metadata (has_next_page, next_cursor).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetRetweetersCursorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /twitter/tweets-favoriters:
    post:
      tags:
      - Tweet Engagement Endpoints
      summary: Get Favoriters
      description: Get favoriters
      operationId: get_favoriters_api_endpoint_twitter_tweets_favoriters_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetFavoritersQuery'
        required: true
      responses:
        '200':
          description: A list of user objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchUserResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
  /twitter/tweets/quotes/page:
    post:
      tags:
      - Tweet Engagement Endpoints
      summary: Get Quote Tweets by Page
      description: Retrieve quote tweets using cursor-based pagination. Each page returns up to 20 tweets. Use `Latest` for chronological order or `Top` for ranked results. Pass next_cursor from the previous response to continue.
      operationId: get_quotes_page_endpoint_twitter_tweets_quotes_page_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetQuotesCursorQuery'
        required: true
      responses:
        '200':
          description: Current page data (up to 20 quote tweets) and pagination metadata (has_next_page, next_cursor).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetQuotesCursorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - HTTPBearer: []
components:
  schemas:
    StreamModel:
      properties:
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
          description: URL of the video stream
          example: https://video.twimg.com/...
        bitrate:
          anyOf:
          - type: integer
          - type: 'null'
          title: Bitrate
          description: Bitrate of the video stream in bps
          example: 832000
        content_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Content Type
          description: Content type of the stream
          example: video/mp4
      type: object
      title: StreamModel
    GetQuotesCursorResponse:
      properties:
        code:
          type: integer
          title: Code
          description: The status code of the response.
        msg:
          type: string
          title: Msg
          description: The message of the response.
        data:
          items:
            $ref: '#/components/schemas/TweetModel'
          type: array
          title: Data
          description: A list of quote tweet objects for the current page.
        has_next_page:
          type: boolean
          title: Has Next Page
          description: Whether another page is available.
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
          description: Use this cursor to fetch the next page when has_next_page is true.
          examples:
          - scroll:thGQYTMwMjU5NDA4ODc4ODc6MjU5NDA4ODc4ODc6
      type: object
      required:
      - code
      - msg
      - data
      - has_next_page
      title: GetQuotesCursorResponse
    GetRetweetersCursorResponse:
      properties:
        code:
          type: integer
          title: Code
          description: The status code of the response.
        msg:
          type: string
          title: Msg
          description: The message of the response.
        data:
          items:
            $ref: '#/components/schemas/UserModel'
          type: array
          title: Data
          description: A list of user objects for the current page.
        has_next_page:
          type: boolean
          title: Has Next Page
          description: Whether another page is available.
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
          description: Use this cursor to fetch the next page when has_next_page is true.
          examples:
          - eyJpZCI6IjIwNjAwNTE1Mzg3OTQ0Mzg2NzciLCJmbG9ja0N1cnNvciI6IjQ2MTE2ODYwMTg2Mjg5ODcxNzkiLCJvcmlnaW5hbERpcmVjdGlvbiI6IkRlc2NlbmRpbmcifQ==-999995
      type: object
      required:
      - code
      - msg
      - data
      - has_next_page
      title: GetRetweetersCursorResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SearchUserResponse:
      properties:
        code:
          type: integer
          title: Code
          description: The status code of the response.
        msg:
          type: string
          title: Msg
          description: The message of the response.
        data:
          items:
            $ref: '#/components/schemas/UserModel'
          type: array
          title: Data
          description: A list of user objects.
      type: object
      required:
      - code
      - msg
      - data
      title: SearchUserResponse
    UserModel:
      properties:
        id:
          type: string
          title: Id
          description: User ID
          example: '1717001045992251392'
        name:
          type: string
          title: Name
          description: Display name
          example: Cryptoklepto
        screen_name:
          type: string
          title: Screen Name
          description: Twitter username
          example: CK_Cryptoklepto
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
          description: Account creation date
          example: Mon Oct 28 02:32:47 +0000 2024
        created_at_datetime:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At Datetime
          description: Account creation datetime in ISO format
          example: '2024-10-28T02:32:47.000Z'
        can_dm:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Can Dm
          description: Whether the user can be direct messaged
          default: false
        can_media_tag:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Can Media Tag
          description: Whether the user can be tagged in media
          default: false
        default_profile:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Default Profile
          description: Whether the user has a default profile
          default: false
        default_profile_image:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Default Profile Image
          description: Whether the user has a default profile image
          default: false
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: User's bio description
          default: ''
        description_urls:
          items:
            type: string
          type: array
          title: Description Urls
          description: List of URLs found in the user's description
          default: []
        urls:
          anyOf:
          - items:
              $ref: '#/components/schemas/urlModel'
            type: array
          - type: 'null'
          title: Urls
          description: List of URLs found in the user's profile
        fast_followers_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Fast Followers Count
          description: Count of fast followers
          default: 0
        favourites_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Favourites Count
          description: Number of tweets the user has liked
          default: 0
        followers_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Followers Count
          description: Number of followers
          default: 0
        following_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Following Count
          description: Number of users this user is following
          default: 0
        has_custom_timelines:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Has Custom Timelines
          description: Whether the user has custom timelines
          default: false
        is_blue_verified:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Blue Verified
          description: Blue verification status
          default: false
        verified_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Verified Type
          description: 'Verification badge type when not blue-only: blue, business, government, etc.'
          examples:
          - government
          - business
          - blue
        is_verified:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Verified
          description: True if the account has any verification badge (blue, business, government, or legacy verified)
          default: false
        profile_image_shape:
          anyOf:
          - type: string
          - type: 'null'
          title: Profile Image Shape
          description: Profile image shape (Circle or Square; Square often indicates business/government)
          examples:
          - Circle
          - Square
        is_translator:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Translator
          description: Whether the user is a translator
          default: false
        listed_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Listed Count
          description: Number of public lists the user is a member of
          default: 0
        location:
          anyOf:
          - type: string
          - type: 'null'
          title: Location
          description: User's location
          default: ''
          example: New York, USA
        media_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Media Count
          description: Number of media tweets posted by the user
          default: 0
        normal_followers_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Normal Followers Count
          description: Count of normal followers
          default: 0
        pinned_tweet_ids:
          items:
            type: string
          type: array
          title: Pinned Tweet Ids
          description: List of pinned tweet IDs
          default: []
        possibly_sensitive:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Possibly Sensitive
          description: Whether the user's profile may contain sensitive content
          default: false
        profile_banner_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Profile Banner Url
          description: URL of the user's profile banner
        profile_image_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Profile Image Url
          description: URL of the user's profile image
        protected:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Protected
          description: Whether the user's tweets are protected
          default: false
        statuses_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Statuses Count
          description: Number of tweets posted by the user
          default: 0
      type: object
      required:
      - id
      - name
      - screen_name
      title: UserModel
    GetFavoritersQuery:
      properties:
        tweet_id:
          type: string
          title: Tweet Id
          description: The ID of the tweet to get favoriters.
        target_count:
          type: integer
          title: Target Count
          description: The number of favoriters to get.
        cookie:
          type: string
          title: Cookie
          description: The user's own authorized Twitter session credentials or auth_token (BYOC — Bring Your Own Cookie). Stateless proxy execution with zero credential retention. See [Authentication Security](/authentication#write-operations--byoc-bring-your-own-cookie) and [How to get Cookie](https://youtube-promotion.pages.dev/how-to-get-twitter-cookie).
          example: ct0=abc123... or 2c4a4e1832096aa694c739b83c83b6d96d43eba7
      type: object
      required:
      - tweet_id
      - target_count
      - cookie
      title: GetFavoritersQuery
    urlModel:
      properties:
        url:
          type: string
          title: Url
          description: URL
          example: https://www.google.com
        expanded_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Expanded Url
          description: Expanded URL
          example: https://www.google.com
        display_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Url
          description: Display URL
          example: www.google.com
      type: object
      required:
      - url
      title: urlModel
    MediaModel:
      properties:
        id:
          type: string
          title: Id
          description: Media ID
          example: '1802991873836883968'
        type:
          type: string
          title: Type
          description: Type of media (e.g., photo, video)
          example: photo
        display_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Display Url
          description: URL of the media to display
          example: pic.twitter.com/...
        expanded_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Expanded Url
          description: Expanded URL for the media
        media_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Media Url
          description: Direct URL to the media file
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
          description: t.co URL for the media
        height:
          anyOf:
          - type: integer
          - type: 'null'
          title: Height
          description: Height of the media in pixels
          example: 1080
        width:
          anyOf:
          - type: integer
          - type: 'null'
          title: Width
          description: Width of the media in pixels
          example: 1920
        features:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Features
          description: Features of the media
        original_info:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Original Info
          description: Original information about the media
        sizes:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Sizes
          description: Available sizes of the media
        source_status_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Source Status Id
          description: Source tweet ID if the media is a retweet
        source_user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Source User Id
          description: Source user ID if the media is a retweet
        duration_millis:
          anyOf:
          - type: integer
          - type: 'null'
          title: Duration Millis
          description: Duration of the video in milliseconds
        aspect_ratio:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Aspect Ratio
          description: Aspect ratio of the video
          example:
          - 16
          - 9
        video_info:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Video Info
          description: Detailed video information
        streams:
          items:
            $ref: '#/components/schemas/StreamModel'
          type: array
          title: Streams
          description: List of available video streams
          default: []
      type: object
      required:
      - id
      - type
      title: MediaModel
    TweetModel:
      properties:
        tweet_id:
          type: string
          title: Tweet Id
          description: The unique identifier for the Tweet
          example: '2104354931595423762'
        is_paid_promotion:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Paid Promotion
          description: Indicates whether the content or user is associated with a paid promotion
          default: false
          example: true
        text:
          type: string
          title: Text
          description: The actual text content of the Tweet
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
          description: The date and time the Tweet was created
          example: Mon Jun 17 03:51:48 +0000 2024
        created_at_datetime:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At Datetime
          description: The ISO 8601 format of the creation date
          example: '2024-06-17T03:51:48.000Z'
        bookmark_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Bookmark Count
          description: Number of times the Tweet has been bookmarked
          default: 0
        bookmarked:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Bookmarked
          description: Indicates if the authenticating user has bookmarked this Tweet
          default: false
        community_note:
          anyOf:
          - type: string
          - type: 'null'
          title: Community Note
          description: Community note associated with the Tweet
        edit_tweet_ids:
          items:
            type: string
          type: array
          title: Edit Tweet Ids
          description: A list of Tweet IDs for each edit of the Tweet
          default: []
        editable_until_msecs:
          anyOf:
          - type: string
          - type: 'null'
          title: Editable Until Msecs
          description: Timestamp for when the Tweet is no longer editable
        edits_remaining:
          anyOf:
          - type: string
          - type: 'null'
          title: Edits Remaining
          description: Number of edits remaining for the Tweet
        favorite_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Favorite Count
          description: Number of likes (favorites) for the Tweet
          default: 0
        favorited:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Favorited
          description: Indicates if the authenticating user has liked this Tweet
          default: false
        full_text:
          anyOf:
          - type: string
          - type: 'null'
          title: Full Text
          description: The full text of the Tweet, especially for extended tweets
        has_card:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Has Card
          description: Indicates if the Tweet has a card attached
          default: false
        has_community_notes:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Has Community Notes
          description: Indicates if the Tweet has community notes
          default: false
        hashtags:
          items:
            type: string
          type: array
          title: Hashtags
          description: A list of hashtags mentioned in the Tweet
          default: []
          example:
          - AI
          - Python
        cashtags:
          items:
            type: string
          type: array
          title: Cashtags
          description: A list of cashtags (stock symbols) mentioned in the Tweet
          default: []
          example:
          - $TSLA
        id:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
          description: The unique identifier for the Tweet (same as tweet_id)
        in_reply_to:
          anyOf:
          - type: string
          - type: 'null'
          title: In Reply To
          description: ID of the Tweet this is a reply to
        in_reply_to_user_id:
          anyOf:
          - type: string
          - type: 'null'
          title: In Reply To User Id
          description: ID of the user this is a reply to
        in_reply_to_screen_name:
          anyOf:
          - type: string
          - type: 'null'
          title: In Reply To Screen Name
          description: Screen name of the user this is a reply to
        is_edit_eligible:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Edit Eligible
          description: Indicates if the Tweet is eligible for editing
          default: false
        is_quote_status:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Quote Status
          description: Indicates if this Tweet is a quote of another Tweet
          default: false
        quoted_status_id_str:
          anyOf:
          - type: string
          - type: 'null'
          title: Quoted Status Id Str
          description: The unique identifier for the Tweet that this is a quote of
        is_translatable:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Translatable
          description: Indicates if the Tweet is translatable
          default: false
        lang:
          anyOf:
          - type: string
          - type: 'null'
          title: Lang
          description: The BCP 47 language identifier for the Tweet's content
          example: en
        media:
          items:
            $ref: '#/components/schemas/MediaModel'
          type: array
          title: Media
          description: A list of media objects (photos, videos) attached to the Tweet
          default: []
        place:
          anyOf:
          - type: string
          - type: 'null'
          title: Place
          description: The location associated with the Tweet
        poll:
          anyOf:
          - type: string
          - type: 'null'
          title: Poll
          description: A poll attached to the Tweet
        possibly_sensitive:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Possibly Sensitive
          description: Indicates if the Tweet may contain sensitive content
        possibly_sensitive_editable:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Possibly Sensitive Editable
          description: Indicates if the sensitive content flag is editable
        quote:
          anyOf:
          - $ref: '#/components/schemas/TweetModel'
          - type: 'null'
          description: The Tweet object being quoted
        quote_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Quote Count
          description: Number of times this Tweet has been quoted
          default: 0
        related_tweets:
          items:
            $ref: '#/components/schemas/TweetModel'
          type: array
          title: Related Tweets
          description: A list of related Tweets
          default: []
        replies:
          items:
            $ref: '#/components/schemas/TweetModel'
          type: array
          title: Replies
          description: A list of replies to this Tweet
          default: []
        reply_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Reply Count
          description: Number of replies to this Tweet
          default: 0
        reply_to:
          anyOf:
          - $ref: '#/components/schemas/TweetModel'
          - type: 'null'
          description: The Tweet object this is a reply to
        retweet_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Retweet Count
          description: Number of times this Tweet has been retweeted
          default: 0
        retweeted_tweet:
          anyOf:
          - $ref: '#/components/schemas/TweetModel'
          - type: 'null'
          description: The original Tweet object if this is a retweet
        thread:
          anyOf:
          - items:
              $ref: '#/components/schemas/TweetModel'
            type: array
          - type: 'null'
          title: Thread
          description: The conversation thread ID
        thumbnail_title:
          anyOf:
          - type: string
          - type: 'null'
          title: Thumbnail Title
          description: Title for the thumbnail in a card
        thumbnail_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Thumbnail Url
          description: URL for the thumbnail in a card
        urls:
          items:
            type: string
          type: array
          title: Urls
          description: A list of URLs included in the Tweet
          default: []
        user:
          anyOf:
          - $ref: '#/components/schemas/UserModel'
          - type: 'null'
          description: The user who posted the Tweet
        view_count:
          anyOf:
          - type: string
          - type: 'null'
          title: View Count
          description: Number of views for the Tweet
        view_count_state:
          anyOf:
          - type: string
          - type: 'null'
          title: View Count State
          description: State of the view count
        status:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Status
          description: Raw status dictionary
        target_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Target Count
          description: The target count of items requested, for context
      type: object
      required:
      - tweet_id
      - text
      title: TweetModel
    GetRetweetersCursorQuery:
      properties:
        tweet_id:
          type: string
          title: Tweet Id
          description: The ID of the tweet to get retweeters for.
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
          description: Cursor returned by the previous page. Leave empty to fetch the first page.
          examples:
          - ''
      type: object
      required:
      - tweet_id
      title: GetRetweetersCursorQuery
    GetQuotesCursorQuery:
      properties:
        tweet_id:
          type: string
          title: Tweet Id
          description: The ID of the tweet to get quote tweets for.
        sort_by:
          type: string
          enum:
          - Top
          - Latest
          title: Sort By
          description: Sort order for quote tweets. `Latest` for chronological order or `Top` for ranked results.
          default: Top
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
          description: Cursor returned by the previous page. Leave empty to fetch the first page.
          examples:
          - ''
      type: object
      required:
      - tweet_id
      title: GetQuotesCursorQuery
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer