openapi: 3.1.0
info:
  title: xAPIs — Twitter / X Data API
  description: "Credit-based Twitter / X data API. Authenticate with your X-API-Key header and call any endpoint below. Each call deducts the number of credits shown in x-credits."
  version: "1.0.0"
servers:
  - url: "https://v2.xapis.dev"
    description: Production API base URL
security:
  - apiKeyAuth: []
paths:
  /twitter/user/info:
    get:
      operationId: "user_info"
      summary: "Get user info"
      description: "Return a complete profile for any public Twitter account, including counts, verification, and account metadata. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "User"
      x-credits: 1
      parameters:
        - name: "userName"
          in: query
          required: true
          description: "The @handle of the account, without the @ symbol."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "data": {
                      "userName": "elonmusk",
                      "name": "Elon Musk",
                      "isBlueVerified": true,
                      "followers": 240376815,
                      "following": 1147,
                      "statusesCount": 73820,
                      "createdAt": "Tue Jun 02 20:12:29 +0000 2009"
                    }
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/user/last_tweets:
    get:
      operationId: "user_last_tweets"
      summary: "Get user tweets"
      description: "Fetch the most recent tweets from an account, with full engagement metrics and media attachments. Cursor-paginated. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "User"
      x-credits: 15
      parameters:
        - name: "userName"
          in: query
          required: true
          description: "The @handle to fetch tweets for."
          schema:
            type: string
        - name: "includeReplies"
          in: query
          required: false
          description: "Include replies in the timeline. Defaults to false."
          schema:
            type: boolean
        - name: "cursor"
          in: query
          required: false
          description: "Pagination cursor for the next page."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "data": {
                      "tweets": [
                        {
                          "id": "1789045512370",
                          "text": "Exciting times ahead",
                          "likeCount": 482103,
                          "retweetCount": 39201,
                          "createdAt": "Thu Jun 18 14:02:00 +0000 2026"
                        }
                      ],
                      "categorized": { "tweets": [], "articles": [], "reposted": [] }
                    },
                    "next_cursor": "77a1c0f3"
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/user/followers:
    get:
      operationId: "user_followers"
      summary: "Get followers"
      description: "Page through the followers of an account. Results are cursor-paginated and return lightweight user objects. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "User"
      x-credits: 30
      parameters:
        - name: "userName"
          in: query
          required: true
          description: "The @handle to fetch followers for."
          schema:
            type: string
        - name: "pageSize"
          in: query
          required: false
          description: "Results per page. Defaults to 40."
          schema:
            type: integer
        - name: "cursor"
          in: query
          required: false
          description: "Pagination cursor returned by the previous page."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "data": {
                      "users": [
                        { "userName": "sama", "name": "Sam Altman", "followers": 3940122 },
                        { "userName": "paulg", "name": "Paul Graham", "followers": 1820455 }
                      ],
                      "next_cursor": "1894e7c9b2"
                    }
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/user/search:
    get:
      operationId: "user_search"
      summary: "Search users"
      description: "Search for users by keyword. Returns matching public profiles. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "User"
      x-credits: 18
      parameters:
        - name: "query"
          in: query
          required: true
          description: "Keyword or phrase to search user profiles for."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "data": [
                      { "userName": "openai", "name": "OpenAI", "isBlueVerified": true, "followers": 3120044 }
                    ]
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/tweets:
    get:
      operationId: "tweets_by_ids"
      summary: "Get tweets by IDs"
      description: "Retrieve one or more tweets by ID with full metadata: author, engagement metrics, and media. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "Tweet"
      x-credits: 1
      parameters:
        - name: "tweet_ids"
          in: query
          required: true
          description: "Comma-separated list of numeric tweet IDs."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "data": {
                      "tweets": [
                        {
                          "id": "1789045512370",
                          "text": "Exciting times ahead",
                          "author": { "userName": "elonmusk", "isBlueVerified": true },
                          "likeCount": 482103,
                          "retweetCount": 39201,
                          "replyCount": 12876,
                          "createdAt": "Thu Jun 18 14:02:00 +0000 2026"
                        }
                      ]
                    }
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/tweet/replies:
    get:
      operationId: "tweet_replies"
      summary: "Get tweet replies"
      description: "Fetch the replies to a tweet, cursor-paginated. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "Tweet"
      x-credits: 15
      parameters:
        - name: "tweetId"
          in: query
          required: true
          description: "The numeric ID of the tweet."
          schema:
            type: string
        - name: "cursor"
          in: query
          required: false
          description: "Pagination cursor for the next page."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "tweets": [
                      { "id": "1789102233445", "text": "Congrats!", "likeCount": 1204 }
                    ],
                    "next_cursor": "c91b2e7",
                    "has_next_page": true
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/tweet/advanced_search:
    get:
      operationId: "advanced_search"
      summary: "Advanced tweet search"
      description: "Search recent tweets with advanced query operators, type filters, and cursor pagination. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "Tweet"
      x-credits: 15
      parameters:
        - name: "query"
          in: query
          required: true
          description: "Search query. Supports operators like from:, #hashtag, and \"exact phrase\"."
          schema:
            type: string
        - name: "queryType"
          in: query
          required: false
          description: "Either \"Latest\" or \"Top\". Defaults to \"Latest\"."
          schema:
            type: string
        - name: "cursor"
          in: query
          required: false
          description: "Pagination cursor for the next page."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "tweets": [
                      { "id": "1789102233445", "text": "Shipping with the xAPIs API today", "likeCount": 1204 }
                    ],
                    "next_cursor": "c91b2e7",
                    "has_next_page": true
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/community/info:
    get:
      operationId: "community_info"
      summary: "Get community info"
      description: "Return details for a Twitter Community, including name, description, and member counts. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "Community"
      x-credits: 1
      parameters:
        - name: "community_id"
          in: query
          required: true
          description: "The numeric ID of the community."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "data": {
                      "name": "Build in Public",
                      "description": "Founders shipping in the open.",
                      "memberCount": 48210
                    }
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/trends:
    get:
      operationId: "trends"
      summary: "Get trends"
      description: "Return trending topics for a location (by WOEID), ranked by volume. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "Other"
      x-credits: 8
      parameters:
        - name: "woeid"
          in: query
          required: true
          description: "Where-On-Earth ID. Use 1 for worldwide."
          schema:
            type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "data": {
                      "trends": [
                        { "name": "#WWDC26", "tweet_volume": 184200 },
                        { "name": "Mars", "tweet_volume": 96400 }
                      ]
                    }
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/user/followings:
    get:
      operationId: "user_followings"
      summary: "Get followings"
      description: "Page through the accounts a user follows. Cursor-paginated. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "User"
      x-credits: 30
      parameters:
        - name: "userName"
          in: query
          required: true
          description: "The @handle to fetch followings for."
          schema:
            type: string
        - name: "pageSize"
          in: query
          required: false
          description: "Results per page. Defaults to 40."
          schema:
            type: integer
        - name: "cursor"
          in: query
          required: false
          description: "Pagination cursor for the next page."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "data": {
                      "users": [
                        { "userName": "sama", "name": "Sam Altman", "followers": 3940122 }
                      ],
                      "next_cursor": "1894e7c9b2"
                    }
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/user/about:
    get:
      operationId: "user_about"
      summary: "Get user about"
      description: "Return extended \"about\" profile info for an account. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "User"
      x-credits: 1
      parameters:
        - name: "userName"
          in: query
          required: true
          description: "The @handle of the account."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "data": {
                      "description": "Mars, Cars, Chips, Starships",
                      "location": "",
                      "url": "https://x.com/elonmusk"
                    }
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/user/batch_info_by_ids:
    get:
      operationId: "user_batch_info"
      summary: "Batch user info by IDs"
      description: "Fetch multiple user profiles in one call by numeric user IDs. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "User"
      x-credits: 1
      parameters:
        - name: "userIds"
          in: query
          required: true
          description: "Comma-separated list of numeric user IDs."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "data": [
                      { "id": "44196397", "userName": "elonmusk", "name": "Elon Musk", "followers": 240376815 }
                    ]
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/user/mentions:
    get:
      operationId: "user_mentions"
      summary: "Get user mentions"
      description: "Fetch recent tweets that mention a given user. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "User"
      x-credits: 15
      parameters:
        - name: "userName"
          in: query
          required: true
          description: "The @handle to fetch mentions for."
          schema:
            type: string
        - name: "cursor"
          in: query
          required: false
          description: "Pagination cursor for the next page."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "data": {
                      "tweets": [
                        { "id": "1789110001122", "text": "@elonmusk great launch!", "likeCount": 320 }
                      ]
                    },
                    "next_cursor": "a1b2c3"
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/user/verifiedFollowers:
    get:
      operationId: "user_verified_followers"
      summary: "Get verified followers"
      description: "Return the verified (blue-check) followers of an account. Cursor-paginated. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "User"
      x-credits: 15
      parameters:
        - name: "user_id"
          in: query
          required: true
          description: "Numeric user ID to fetch verified followers for."
          schema:
            type: string
        - name: "cursor"
          in: query
          required: false
          description: "Pagination cursor for the next page."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "data": {
                      "users": [
                        { "userName": "nasa", "name": "NASA", "isBlueVerified": true, "followers": 75200000 }
                      ],
                      "next_cursor": "9f8e7d"
                    }
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/tweet/quotes:
    get:
      operationId: "tweet_quotes"
      summary: "Get tweet quotes"
      description: "Fetch quote tweets of a given tweet. Cursor-paginated. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "Tweet"
      x-credits: 15
      parameters:
        - name: "tweetId"
          in: query
          required: true
          description: "The numeric ID of the tweet."
          schema:
            type: string
        - name: "cursor"
          in: query
          required: false
          description: "Pagination cursor for the next page."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "tweets": [
                      { "id": "1789120033445", "text": "This is huge", "likeCount": 540 }
                    ],
                    "next_cursor": "c91b2e7",
                    "has_next_page": true
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/tweet/retweeters:
    get:
      operationId: "tweet_retweeters"
      summary: "Get retweeters"
      description: "List the users who retweeted a given tweet. Cursor-paginated. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "Tweet"
      x-credits: 18
      parameters:
        - name: "tweetId"
          in: query
          required: true
          description: "The numeric ID of the tweet."
          schema:
            type: string
        - name: "cursor"
          in: query
          required: false
          description: "Pagination cursor for the next page."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "users": [
                      { "userName": "sama", "name": "Sam Altman" }
                    ],
                    "next_cursor": "c91b2e7",
                    "has_next_page": true
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/tweet/thread_context:
    get:
      operationId: "thread"
      summary: "Get thread"
      description: "Return the full conversation thread context for a tweet. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "Tweet"
      x-credits: 15
      parameters:
        - name: "tweetId"
          in: query
          required: true
          description: "The numeric ID of any tweet in the thread."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "tweets": [
                      { "id": "1789045512370", "text": "1/ Here's the plan", "likeCount": 4821 },
                      { "id": "1789045512999", "text": "2/ Step two", "likeCount": 1203 }
                    ],
                    "next_cursor": null,
                    "has_next_page": false
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/article:
    get:
      operationId: "article"
      summary: "Get article"
      description: "Return the full content of a long-form X article. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "Tweet"
      x-credits: 5
      parameters:
        - name: "tweet_id"
          in: query
          required: true
          description: "The numeric ID of the article tweet."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "data": {
                      "article": {
                        "title": "The Future of Spaceflight",
                        "preview_text": "Why reusability changes everything...",
                        "cover_media_img_url": "https://pbs.twimg.com/media/cover.jpg"
                      }
                    }
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/community/members:
    get:
      operationId: "community_members"
      summary: "Get community members"
      description: "List the members of a Twitter Community. Cursor-paginated. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "Community"
      x-credits: 18
      parameters:
        - name: "community_id"
          in: query
          required: true
          description: "The numeric ID of the community."
          schema:
            type: string
        - name: "cursor"
          in: query
          required: false
          description: "Pagination cursor for the next page."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "data": {
                      "members": [ { "userName": "paulg", "name": "Paul Graham" } ],
                      "next_cursor": "m1n2o3"
                    }
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/community/moderators:
    get:
      operationId: "community_moderators"
      summary: "Get community moderators"
      description: "List the moderators of a Twitter Community. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "Community"
      x-credits: 18
      parameters:
        - name: "community_id"
          in: query
          required: true
          description: "The numeric ID of the community."
          schema:
            type: string
        - name: "cursor"
          in: query
          required: false
          description: "Pagination cursor for the next page."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "data": {
                      "moderators": [ { "userName": "jack", "name": "jack" } ]
                    }
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/community/tweets:
    get:
      operationId: "community_tweets"
      summary: "Get community tweets"
      description: "Fetch tweets posted within a Twitter Community. Cursor-paginated. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "Community"
      x-credits: 15
      parameters:
        - name: "community_id"
          in: query
          required: true
          description: "The numeric ID of the community."
          schema:
            type: string
        - name: "cursor"
          in: query
          required: false
          description: "Pagination cursor for the next page."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "data": {
                      "tweets": [ { "id": "1789130055667", "text": "Shipped today!", "likeCount": 88 } ]
                    },
                    "next_cursor": "t1u2v3"
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/community/get_tweets_from_all_community:
    get:
      operationId: "community_all_tweets"
      summary: "Search all communities"
      description: "Search tweets across all Twitter Communities by keyword. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "Community"
      x-credits: 15
      parameters:
        - name: "query"
          in: query
          required: true
          description: "Keyword or phrase to search community tweets for."
          schema:
            type: string
        - name: "cursor"
          in: query
          required: false
          description: "Pagination cursor for the next page."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "data": {
                      "tweets": [ { "id": "1789140077889", "text": "AI agents thread", "likeCount": 412 } ]
                    },
                    "next_cursor": "w1x2y3"
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/user/followers_ids:
    get:
      operationId: "user_followers_ids"
      summary: "Get follower IDs"
      description: "Bulk-fetch the numeric IDs of an account’s followers — lightweight, ideal for graph analysis. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "User"
      x-credits: 5
      parameters:
        - name: "userName"
          in: query
          required: true
          description: "The @handle to fetch follower IDs for."
          schema:
            type: string
        - name: "cursor"
          in: query
          required: false
          description: "Pagination cursor for the next page."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "ids": ["44196397", "1494877848", "12"],
                    "next_cursor": "1894e7c9b2",
                    "has_next_page": true
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/user/timeline:
    get:
      operationId: "user_timeline"
      summary: "Get user timeline"
      description: "Fetch a user’s timeline by numeric user ID (use when you have the ID rather than the handle). All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "User"
      x-credits: 15
      parameters:
        - name: "userId"
          in: query
          required: true
          description: "Numeric user ID to fetch the timeline for."
          schema:
            type: string
        - name: "cursor"
          in: query
          required: false
          description: "Pagination cursor for the next page."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "data": {
                      "tweets": [
                        { "id": "1789045512370", "text": "Exciting times ahead", "likeCount": 482103 }
                      ]
                    },
                    "next_cursor": "77a1c0f3"
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/user/check_follow:
    get:
      operationId: "user_check_follow"
      summary: "Check follow relationship"
      description: "Check whether one account follows another. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "User"
      x-credits: 2
      parameters:
        - name: "userName"
          in: query
          required: true
          description: "The source @handle."
          schema:
            type: string
        - name: "targetUserName"
          in: query
          required: true
          description: "The target @handle to check against."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "data": { "following": true }
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/list/members:
    get:
      operationId: "list_members"
      summary: "Get list members"
      description: "Retrieve the members of a Twitter List. Cursor-paginated. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "List"
      x-credits: 18
      parameters:
        - name: "list_id"
          in: query
          required: true
          description: "The numeric ID of the list."
          schema:
            type: string
        - name: "cursor"
          in: query
          required: false
          description: "Pagination cursor for the next page."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "members": [ { "userName": "paulg", "name": "Paul Graham" } ],
                    "next_cursor": "m1n2o3",
                    "has_next_page": true
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/list/followers:
    get:
      operationId: "list_followers"
      summary: "Get list followers"
      description: "Retrieve the followers of a Twitter List. Cursor-paginated. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "List"
      x-credits: 18
      parameters:
        - name: "list_id"
          in: query
          required: true
          description: "The numeric ID of the list."
          schema:
            type: string
        - name: "cursor"
          in: query
          required: false
          description: "Pagination cursor for the next page."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "followers": [ { "userName": "sama", "name": "Sam Altman" } ],
                    "next_cursor": "f1g2h3",
                    "has_next_page": true
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
  /twitter/list/tweets:
    get:
      operationId: "list_tweets"
      summary: "Get list tweets"
      description: "Fetch tweets posted to a Twitter List. Cursor-paginated. All responses are wrapped in a standard envelope: `{ \"status\": \"success\", \"msg\": \"...\", \"data\": ... }`."
      tags:
        - "List"
      x-credits: 15
      parameters:
        - name: "listId"
          in: query
          required: true
          description: "The numeric ID of the list."
          schema:
            type: string
        - name: "cursor"
          in: query
          required: false
          description: "Pagination cursor for the next page."
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
              example: |-
                  {
                    "status": "success",
                    "msg": "success",
                    "tweets": [ { "id": "1789150088990", "text": "From the list", "likeCount": 77 } ],
                    "next_cursor": "l1m2n3",
                    "has_next_page": true
                  }
        '401':
          description: "Missing or invalid API key (MISSING_API_KEY / INVALID_API_KEY)."
        '429':
          description: "Insufficient credits (INSUFFICIENT_CREDITS) or rate limited."
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: "Your xAPIs API key. Get one at https://xapis.dev/settings/apikeys"
