openapi: 3.0.0 info: title: SocialData API Reference description: |- SocialData API is a scalable and reliable API that simplifies the process of fetching data from Twitter/X. With SocialData API, you can easily retrieve tweets, user profiles, user followers/following and other information without the need for proxies or parsing Twitter responses. termsOfService: https://socialdata.tools/legal/terms-and-conditions contact: email: support@socialdata.tools version: 1.0.0 externalDocs: description: SocialData API Reference url: https://docs.socialdata.tools security: - bearerAuth: [] servers: - url: https://api.socialdata.tools tags: - name: Data API description: Endpoints for retrieving data from Twitter - name: Monitoring API description: Endpoints for creating and managing your monitors - name: Social Actions API description: Endpoints for validating social actions Twitter - name: SocialData Account Management description: Endpoints for managing your SocialData account paths: /twitter/search: get: summary: Get Search Results tags: - Data API description: Returns array of tweets provided by Twitter search. Typically Twitter returns ~20 results per page. You can request additional search results by sending another request to the same endpoint using cursor parameter. This endpoint supports all Twitter advanced search operators (to be passed within the 'query' value) operationId: getTwitterSearch parameters: - name: query in: query required: true description: A UTF-8, URL-encoded search query, including any operators supported by Twitter advanced search schema: type: string example: from:elonmusk doge -filter:replies - name: cursor in: query required: false description: Cursor value obtained from next_cursor response property. Used to retrieve additional pages for the same query schema: type: string example: DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0d - name: type in: query required: false description: Search type (Latest for recent tweets or Top for popular tweets). Default - Latest schema: type: string enum: [Latest, Top] example: Top responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/TweetsResponse' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. one of the required parameters was not provided) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-search-results/ /twitter/user/{username}: get: tags: - Data API summary: Get User Profile by Username description: Retrieve detailed user information by their Twitter username. operationId: getTwitterUserByUsername parameters: - name: username in: path required: true description: The username of the target user profile without @. schema: type: string example: elonmusk responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/User' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested user does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. invalid username format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-user-profile/ /twitter/user/{user_id}: get: tags: - Data API summary: Get User Profile by ID description: Retrieve detailed user profile information by their Twitter numerical ID. operationId: getTwitterUserById parameters: - name: user_id in: path required: true description: The numerical ID of the target user profile. When using languages where the user_id value exceeds the default Integer type limit (e.g., JavaScript), you should store user_id as a String. Use the id_str property returned by the API for these values. schema: type: string example: 44196397 responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/User' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested user does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. invalid user ID format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-user-profile/ /twitter/users-by-ids: post: tags: - Data API summary: Get Multiple User Profiles by IDs description: Retrieve user information for up to 100 Twitter users in a single request. operationId: getMultipleTwitterUsers requestBody: required: true content: application/json: schema: type: object properties: ids: type: array description: An array of Twitter user IDs. Up to 100 IDs per request. When using languages where the user_id value exceeds the default Integer type limit (e.g., JavaScript), you should store user_id as a String. Use the id_str property returned by the API for these values. maxItems: 100 items: type: string required: - ids example: ids: ["44196397", "1319287761048723458"] responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/UsersWithoutCursorResponse' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. more than 100 IDs provided or invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-multiple-user-profiles/ /twitter/users-by-usernames: post: tags: - Data API summary: Get Multiple User Profiles By Usernames description: Retrieve user information for up to 100 Twitter users in a single request based on array of usernames. operationId: getMultipleTwitterUsersByUsernames requestBody: required: true content: application/json: schema: type: object properties: usernames: type: array description: An array of Twitter usernames. Up to 100 usernames per request. maxItems: 100 items: type: string required: - usernames example: usernames: ["elonmusk", "realdonaldtrump"] responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/UsersWithoutCursorResponse' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. more than 100 usernames provided or invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-multiple-user-profiles-by-usernames/ /twitter/tweets-by-ids: post: tags: - Data API summary: Get Multiple Tweets description: Retrieve contents and stats for up to 100 tweets in a single request. Returns an array of tweet objects. Tweets that could not be retrieved are omitted from the array, so the response may contain fewer items than the number of IDs requested. operationId: getMultipleTweets requestBody: required: true content: application/json: schema: type: object properties: ids: type: array description: An array of Twitter tweet IDs. Up to 100 IDs per request. When using languages where the tweet ID value exceeds the default Integer type limit (e.g. JavaScript), you should store the ID as a String. Use the id_str property returned by the API for these values. maxItems: 100 items: type: string required: - ids example: ids: ["1922917671227498515", "1924473372236476749"] responses: '200': description: Request succeeded content: application/json: schema: type: array items: $ref: '#/components/schemas/Tweet' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested tweet does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. more than 100 IDs provided or invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-multiple-tweets/ /twitter/user/{user_id}/followers: get: tags: - Data API summary: Get User Followers description: | Returns an array of user profiles that are following the target profile identified by user_id. The profiles are returned in reverse chronological order, with the most recent followers appearing on the first page. operationId: getTwitterUserFollowers parameters: - name: user_id in: path required: true description: The numeric ID of the desired user. When using languages where the user_id value exceeds the default Integer type limit (e.g., JavaScript), you should store user_id as a String. Use the id_str property returned by the API for these values. schema: type: string example: "1625802236571033602" - name: cursor in: query required: false description: Cursor value obtained from next_cursor response property. Use this value to retrieve additional pages. Omit this value to retrieve the first page. schema: type: string example: 4611686018541662731|1741085517660815316 responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/UsersResponse' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested user not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. user_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-user-followers/ /twitter/user/{user_id}/verified-followers: get: tags: - Data API summary: Get User Verified Followers description: | Returns an array of verified user profiles that are following the target profile identified by user_id. The profiles are returned in reverse chronological order, with the most recent followers appearing on the first page. operationId: getTwitterUserVerifiedFollowers parameters: - name: user_id in: path required: true description: The numeric ID of the desired user. When using languages where the id value exceeds the default Integer type limit (e.g., JavaScript), you should store id as a String. Use the id_str property returned by the API for these values. schema: type: string example: 1625802236571033602 - name: cursor in: query required: false description: Cursor value obtained from next_cursor response property. Use this value to retrieve additional pages. Omit this value to retrieve the first page. schema: type: string example: 4611686018541662731|1741085517660815316 responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/UsersResponse' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested user not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. user_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-user-verified-followers/ /twitter/user/{user_id}/following: get: tags: - Data API summary: Get User Following List description: | Returns an array of user profiles that the target profile identified by user_id is following. The profiles are returned in reverse chronological order, with the most recently followed profiles appearing on the first page. operationId: getTwitterUserFollowing parameters: - name: user_id in: path required: true description: The numeric ID of the desired user. When using languages where the user_id value exceeds the default Integer type limit (e.g., JavaScript), you should store user_id as a String. Use the id_str property returned by the API for these values. schema: type: string example: 1729591119699124560 - name: cursor in: query required: false description: Cursor value obtained from next_cursor response property. Use this value to retrieve additional pages. Omit this value to retrieve the first page. schema: type: string example: 4611686018541662731|1741085517660815316 responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/UsersResponse' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested user not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. user_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-user-followings/ /twitter/user/{user_id}/tweets: get: tags: - Data API summary: Get User's Tweets description: | Returns array of tweets from the user's tweets timeline. Typically Twitter returns ~20 results per page. You can request additional search results by sending another request to the same endpoint using cursor parameter. The endpoint only works with profiles that are 'public' and will fail to retrieve tweets for profiles with 'protected' privacy setting. operationId: getTwitterUserTweets parameters: - name: user_id in: path required: true description: The numerical ID of the desired user. When using languages where the user_id value exceeds the default Integer type limit (e.g., JavaScript), you should store user_id as a String. Use the id_str property returned by the API for these values. schema: type: string example: 443198458 - name: cursor in: query required: false description: Cursor value obtained from `next_cursor` response property. Use this parameter to retrieve additional pages. Omit this parameter to retrieve the first page. Cursor may contain spaces and other special characters, therefore always remember to URL-encode the value. schema: type: string example: DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0d responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/TweetsResponse' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested user not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. user_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-user-tweets-replies/ /twitter/user/{user_id}/tweets-and-replies: get: tags: - Data API summary: Get User's Tweets and Replies description: | Returns array of tweets from the user's tweets and replies timeline, including both original tweets and replies. Typically Twitter returns ~20 results per page. You can request additional search results by sending another request to the same endpoint using cursor parameter. The endpoint only works with profiles that are 'public' and will fail to retrieve tweets for profiles with 'protected' privacy setting. operationId: getTwitterUserTweetsAndReplies parameters: - name: user_id in: path required: true description: The numerical ID of the desired user. When using languages where the user_id value exceeds the default Integer type limit (e.g., JavaScript), you should store user_id as a String. Use the id_str property returned by the API for these values. schema: type: string example: 443198458 - name: cursor in: query required: false description: Cursor value obtained from `next_cursor` response property. Use this parameter to retrieve additional pages. Omit this parameter to retrieve the first page. Cursor may contain spaces and other special characters, therefore always remember to URL-encode the value. schema: type: string example: DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0d... responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/TweetsResponse' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested user not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. user_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-user-tweets-replies/ /twitter/user/{username}/mentions: get: tags: - Data API summary: Get User Mentions description: Retrieves tweets that mention the specified Twitter user. Typically returns ~20 results per page. You can request additional results by sending another request to the same endpoint using cursor parameter. operationId: getTwitterUserMentions parameters: - name: username in: path required: true description: Username of the target user profile without @. schema: type: string example: elonmusk - name: cursor in: query required: false description: Cursor value obtained from `next_cursor` response property. Use this parameter to retrieve additional pages. Omit this parameter to retrieve the first page. schema: type: string example: 1890084840239985036 responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/TweetsResponse' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested user does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. username is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-user-mentions/ /twitter/user/{user_id}/highlights: get: tags: - Data API summary: Get User Highlighted Tweets description: | Returns array of tweets from the user's Highlights tab. Typically Twitter returns ~20 results per page. You can request additional results by sending another request to the same endpoint using cursor parameter. operationId: getTwitterUserHighlights parameters: - name: user_id in: path required: true description: The numeric ID of the desired user. When using languages where the user_id value exceeds the default Integer type limit (e.g., JavaScript), you should store user_id as a String. Use the id_str property returned by the API for these values. schema: type: string example: "1729591119699124560" - name: cursor in: query required: false description: Cursor value obtained from `next_cursor` response property. Use this parameter to retrieve additional pages. Omit this parameter to retrieve the first page. Cursor may contain spaces and other special characters, therefore always remember to URL-encode the value. schema: type: string example: DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0d... responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/TweetsResponse' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested user not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. user_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-user-highlights/ /twitter/user/{user_id}/affiliates: get: tags: - Data API summary: Get User Affiliates description: | Verified organization profiles (i.e. users with the gold checkmark) occasionally have affiliated accounts listed under "Affiliates" tab on their profile page. The endpoint returns an array of user profiles affiliated with this organization. operationId: getTwitterUserAffiliates parameters: - name: user_id in: path required: true description: The numeric ID of the desired user. When using languages where the user_id value exceeds the default Integer type limit (e.g., JavaScript), you should store user_id as a String. Use the id_str property returned by the API for these values. schema: type: string example: 1729591119699124560 - name: cursor in: query required: false description: Cursor value obtained from `next_cursor` response property. Use this parameter to retrieve additional pages. Omit this parameter to retrieve the first page. Cursor may contain spaces and other special characters, therefore always remember to URL-encode the value. schema: type: string example: DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0d... responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/UsersResponse' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested user not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. user_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-user-affiliates/ /twitter/user/{user_id}/lists: get: tags: - Data API summary: Get User's Lists description: | Returns array of lists a user created or is subscribed to. Typically Twitter returns up to 100 lists per page. You can request additional results by sending another request to the same endpoint using cursor parameter. operationId: getTwitterUserLists parameters: - name: user_id in: path required: true description: The numeric ID of the desired user. When using languages where the user_id value exceeds the default Integer type limit (e.g., JavaScript), you should store user_id as a String. Use the id_str property returned by the API for these values. schema: type: string example: 1729591119699124560 - name: cursor in: query required: false description: Cursor value obtained from `next_cursor` response property. Use this parameter to retrieve additional pages. Omit this parameter to retrieve the first page. Cursor may contain spaces and other special characters, therefore always remember to URL-encode the value. schema: type: string example: DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0d... responses: '200': description: Request succeeded content: application/json: schema: type: object properties: next_cursor: type: string description: Cursor for pagination to get the next page of results lists: type: array items: type: object required: - next_cursor - lists '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested user not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. user_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-user-lists/ /twitter/user/{username}/extended-bio: get: tags: - Data API summary: Get User's Extended Twitter Bio description: | Returns an object with user's extended bio with all text and formatting details, or an empty object if the extended bio is missing. operationId: getTwitterUserExtendedBio parameters: - name: username in: path required: true description: Username of the target user profile without @. schema: type: string example: elonmusk responses: '200': description: Request succeeded content: application/json: schema: oneOf: - type: object description: Extended bio object with formatting details - type: object description: Empty object if extended bio is missing '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested user not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. username is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-user-extended-bio/ /twitter/user/{user_id}/similar: get: tags: - Data API summary: Get Similar User Profiles description: Returns an array of user profiles that Twitter/X considers similar to a given user. operationId: getTwitterUserSimilarProfiles parameters: - name: user_id in: path required: true description: The numeric ID of the desired user. When using languages where the user_id value exceeds the default Integer type limit (e.g. JavaScript), you should store user_id as a String. Use the id_str property returned by the API for these values. schema: type: string example: "1729591119699124560" responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/UsersWithoutCursorResponse' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-user-similar-profiles/ /twitter/tweets/{tweet_id}: get: tags: - Data API summary: Get Tweet description: Retrieves complete tweet details by its ID. operationId: getTweet parameters: - name: tweet_id in: path required: true description: The numerical ID of the target tweet. When using languages where the tweet_id value exceeds the default Integer type limit (e.g., JavaScript), you should store id as a String. Use the id_str property returned by the API for these values. schema: type: string example: 1729591119699124560 responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/Tweet' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden - tweet not available due to author's privacy settings content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested tweet does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. tweet ID is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-tweet/ /twitter/tweets/{tweet_id}/comments: get: tags: - Data API summary: Get Tweet Comments description: | Returns an array of comments for a given tweet_id. This endpoint only works for top-level tweets (i.e. this can't be used to retrieve comments posted in response to other comments). operationId: getTweetComments parameters: - name: tweet_id in: path required: true description: The numerical ID of the target tweet. When using languages where the id value exceeds the default Integer type limit (e.g., JavaScript), you should store id as a String. Use the id_str property returned by the API for these values. schema: type: string example: 1890269299287441612 - name: cursor in: query required: false description: Cursor value obtained from `next_cursor` response property. Use this parameter to retrieve additional pages. Omit this parameter to retrieve the first page. schema: type: string example: 1890084840239985036 responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/TweetsResponse' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested tweet does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. tweet ID is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-tweet-comments/ /twitter/tweets/{tweet_id}/retweeted_by: get: tags: - Data API summary: Get Tweet Retweeters List description: | This endpoint returns an array of user profiles that retweeted the target tweet identified by tweet_id. The profiles are returned in reverse chronological order, with the most recent retweets appearing on the first page. operationId: getTweetRetweeters parameters: - name: tweet_id in: path required: true description: The numerical ID of the desired Tweet. When using languages where the tweet_id value exceeds the default Integer type limit (e.g., JavaScript), you should store tweet_id as a String. Use the id_str property returned by the API for these values. schema: type: string example: 1729591119699124560 - name: cursor in: query required: false description: Cursor value obtained from `next_cursor` response property. Use this parameter to retrieve additional pages. Omit this parameter to retrieve the first page. Cursor may contain spaces and other special characters, therefore always remember to URL-encode the value. schema: type: string example: HBbS87H7icrezjEAAA== responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/UsersResponse' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested tweet does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. tweet_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-tweet-retweeters/ /twitter/tweets/{tweet_id}/quotes: get: tags: - Data API summary: Get Tweet Quotes description: | Returns an array of quotes for a given tweet_id. This endpoint retrieves tweets that quote the target tweet. operationId: getTweetQuotes parameters: - name: tweet_id in: path required: true description: The numerical ID of the target tweet. When using languages where the id value exceeds the default Integer type limit (e.g., JavaScript), you should store id as a String. Use the id_str property returned by the API for these values. schema: type: string example: "1890269299287441612" - name: cursor in: query required: false description: Cursor value obtained from `next_cursor` response property. Use this parameter to retrieve additional pages. Omit this parameter to retrieve the first page. schema: type: string example: "1890084840239985036" responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/TweetsResponse' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested tweet does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. tweet ID is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /twitter/article/{article_id}: get: tags: - Data API summary: Get Article description: Returns a tweet with an article attached to it. The output contains the same properties as the tweet details endpoint; the article content is returned within the `article` attribute of the response, as X's raw Draft.js document tree. operationId: getTwitterArticle parameters: - name: article_id in: path required: true description: The numerical ID of the desired article tweet. When using languages where the ID value exceeds the default Integer type limit (e.g. JavaScript), you should store it as a String. schema: type: string example: "1799137410284134858" responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/TweetWithArticle' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested tweet does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. article_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-tweet-article/ /v2/twitter/article/{article_id}: get: tags: - Data API summary: Get Article (v2) description: | Returns a Twitter/X article rendered as Markdown. Unlike the v1 Get Article endpoint, which returns X's raw Draft.js document tree as `content_state`, this endpoint renders that tree for you and returns the result as a Markdown string in `markdown`, dropping `content_state` and `media_entities` from the article object. Long ordinary posts and articles are easy to confuse. When the requested ID turns out to be an ordinary post rather than an article, this endpoint renders the post's own text as Markdown instead of failing, and sets `markdown_source` to `tweet_text` with `article` set to null. Both outcomes return 200 and are billed the same, so branch on `markdown_source`. operationId: getTwitterArticleV2 parameters: - name: article_id in: path required: true description: The numerical ID of the post carrying the article. This is the ID of the post itself, not the ID in an x.com/i/article/... URL. When using languages where the ID value exceeds the default Integer type limit (e.g. JavaScript), you should store it as a String. schema: type: string example: "2084992645966016757" responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/TweetWithMarkdown' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested tweet does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. article_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-article-v2/ /twitter/thread/{thread_id}: get: tags: - Data API summary: Get Tweets in a Twitter Thread description: | Returns an array of tweets associated with a thread and a next_cursor value used to retrieve more pages (if the thread contains more than 30 posts). operationId: getTwitterThread parameters: - name: thread_id in: path required: true description: The numerical ID of the desired thread. When using languages where the id value exceeds the default Integer type limit (e.g., JavaScript), you should store id as a String. Use the id_str property returned by the API for these values. schema: type: string example: 1729591119699124560 - name: cursor in: query required: false description: Cursor value obtained from `next_cursor` response property. Use this parameter to retrieve additional pages. Omit this parameter to retrieve the first page. Cursor may contain spaces and other special characters, therefore always remember to URL-encode the value. schema: type: string example: PAAAAPAtPBwcFoCAsrHQ6pOAKxUC... responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/TweetsResponse' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested tweet does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. thread_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-tweet-thread/ /twitter/space/{space_id}: get: tags: - Data API summary: Get Twitter Space Details description: Retrieves detailed information about a Twitter Space by its ID. operationId: getTwitterSpaceDetails parameters: - name: space_id in: path required: true description: The ID of the desired Twitter Space. schema: type: string example: 1jMJgLdenVjxL responses: '200': description: Request succeeded content: application/json: schema: type: object description: Twitter Space details '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - Twitter space not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. space_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-space-details/ /twitter/list/{list_id}: get: tags: - Data API summary: Get List Details description: Retrieves detailed information about a Twitter List by its ID. operationId: getTwitterListDetails parameters: - name: list_id in: path required: true description: The numeric ID of the desired list. When using languages where the list_id value exceeds the default Integer type limit (e.g., JavaScript), you should store list_id as a String. Use the id_str property returned by the API for these values. schema: type: string example: 1625802236571033602 responses: '200': description: Request succeeded content: application/json: schema: type: object description: Twitter List details '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested list not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. list_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-list-details/ /twitter/list/{list_id}/members: get: tags: - Data API summary: Get List Members description: Retrieves members of a Twitter List by its ID. operationId: getTwitterListMembers parameters: - name: list_id in: path required: true description: The numeric ID of the desired list. When using languages where the list_id value exceeds the default Integer type limit (e.g., JavaScript), you should store list_id as a String. Use the id_str property returned by the API for these values. schema: type: string example: 1625802236571033602 - name: cursor in: query required: false description: Cursor value obtained from `next_cursor` response property. Use this parameter to retrieve additional pages. Omit this parameter to retrieve the first page. schema: type: string example: 4611686018541662731|1741085517660815316 responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/UsersResponse' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested list not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. list_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-list-members/ /twitter/list/{list_id}/tweets: get: tags: - Data API summary: Get List Tweets description: Retrieves tweets from a specific Twitter List by its ID. operationId: getTwitterListTweets parameters: - name: list_id in: path required: true description: The numeric ID of the desired list. When using languages where the list_id value exceeds the default Integer type limit (e.g., JavaScript), you should store list_id as a String. Use the id_str property returned by the API for these values. schema: type: string example: "1625802236571033602" - name: cursor in: query required: false description: Cursor value obtained from `next_cursor` response property. Use this parameter to retrieve additional pages. Omit this parameter to retrieve the first page. schema: type: string example: 1890084840239985036 responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/TweetsResponse' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested list not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. list_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-list-tweets/ /twitter/community/{community_id}: get: tags: - Data API summary: Get Community Details description: Returns information about a Twitter community. operationId: getTwitterCommunityDetails parameters: - name: community_id in: path required: true description: Target community ID. When using languages where the community_id value exceeds the default Integer type limit (e.g. JavaScript), you should store community_id as a String. schema: type: string example: "1493446837214187523" responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/Community' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested community does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. community_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-community-details/ /twitter/community/{community_id}/search: get: tags: - Data API summary: Get Community Search Results description: Returns an array of tweets provided by the Twitter community search page. Typically Twitter returns ~20 results per page. You can request additional search results by sending another request to the same endpoint using the cursor parameter. operationId: getTwitterCommunitySearch parameters: - name: community_id in: path required: true description: Target community ID. When using languages where the community_id value exceeds the default Integer type limit (e.g. JavaScript), you should store community_id as a String. schema: type: string example: "1493446837214187523" - name: query in: query required: true description: A UTF-8, URL-encoded search query, including any operators supported by the Twitter website search schema: type: string example: from:elonmusk doge - name: cursor in: query required: false description: Cursor value obtained from `next_cursor` response property. Used to retrieve additional pages for the same query. Cursor may contain spaces and other special characters, therefore always remember to URL-encode the value. schema: type: string example: DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0d - name: type in: query required: false description: Search type (Latest for recent tweets or Top for popular tweets). Default - Latest. schema: type: string enum: [Latest, Top] example: Top responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/TweetsResponse' '402': description: Payment required - not enough credits to perform this request. You should purchase additional credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested community does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. query is not provided) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-community-search-results/ /twitter/community/{community_id}/tweets: get: tags: - Data API summary: Get Community Tweets description: | Returns array of tweets from the community timeline. Typically Twitter returns ~20 results per page. You can request additional results by sending another request to the same endpoint using cursor parameter. If the community has a pinned post - this post will be returned on all subsequent requests made with the cursor. This endpoint doesn't support any filters. operationId: getTwitterCommunityTweets parameters: - name: community_id in: path required: true description: Target community ID. When using languages where the user_id value exceeds the default Integer type limit (e.g., JavaScript), you should store user_id as a String. Use the id_str property returned by the API for these values. schema: type: string example: "1493446837214187523" - name: cursor in: query required: false description: Cursor value obtained from `next_cursor` response property. Use this parameter to retrieve additional pages. Omit this parameter to retrieve the first page. Cursor may contain spaces and other special characters, therefore always remember to URL-encode the value. schema: type: string example: DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0d - name: type in: query required: false description: Search type (Latest for recent tweets or Top for popular tweets). Default - Latest. schema: type: string enum: [Latest, Top] example: Top responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/TweetsResponse' '402': description: Payment required - not enough credits to perform this request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested community does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. community_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-community-tweets/ /twitter/community/{community_id}/members: get: tags: - Data API summary: Get Community Members description: | Returns array of users who are admins, moderators or regular members of a community. Typically Twitter returns ~20 results per page. You can request additional results by sending another request to the same endpoint using cursor parameter. operationId: getTwitterCommunityMembers parameters: - name: community_id in: path required: true description: Target community ID. When using languages where the community_id value exceeds the default Integer type limit (e.g., JavaScript), you should store community_id as a String. Use the id_str property returned by the API for these values. schema: type: string example: "1493446837214187523" - name: cursor in: query required: false description: Cursor value obtained from `next_cursor` response property. Use this parameter to retrieve additional pages. Omit this parameter to retrieve the first page. Cursor may contain spaces and other special characters, therefore always remember to URL-encode the value. schema: type: string example: DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0d responses: '200': description: Request succeeded content: application/json: schema: type: array items: type: object description: User object with community role information '402': description: Payment required - not enough credits to perform this request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested community does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. community_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/reference/get-community-members/ /twitter/user/{source_user_id}/following/{target_user_id}: get: tags: - Social Actions API summary: Verify User Following Relationship description: | This endpoint provides a convenient way to check if a user (identified by source_user_id) is following another user (identified by target_user_id). The endpoint achieves this without scraping the entire followers list which allows us to deliver a fully accurate result with minimal latency. operationId: verifyTwitterUserFollowing parameters: - name: source_user_id in: path required: true description: The numeric ID of the follower user. When using languages where the user_id value exceeds the default Integer type limit (e.g., JavaScript), you should store user_id as a String. Use the id_str property returned by the API for these values. schema: type: string example: "1729591119699124560" - name: target_user_id in: path required: true description: The numeric ID of the user being followed. When using languages where the user_id value exceeds the default Integer type limit (e.g., JavaScript), you should store user_id as a String. Use the id_str property returned by the API for these values. schema: type: string example: "1729591119699124560" responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/UserFollowingResponse' '402': description: Payment required - not enough credits to perform this request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested target user does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. user IDs are not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/social-actions/verify-user-following/ /twitter/tweets/{tweet_id}/retweeted_by/{user_id}: get: tags: - Social Actions API summary: Verify User Retweeted a Tweet description: | This endpoint provides a convenient way to check if a user retweeted a tweet identified by tweet_id. This will recursively retrieve all users who recently retweeted a tweet and check if the user_id is present among the retrieved users. operationId: verifyTwitterUserRetweeted parameters: - name: tweet_id in: path required: true description: The numeric ID of the target tweet. When using languages where the id value exceeds the default Integer type limit (e.g., JavaScript), you should store id as a String. Use the id_str property returned by the API for these values. schema: type: string example: "1625802236571033602" - name: user_id in: path required: true description: The numeric ID of the user. When using languages where the id value exceeds the default Integer type limit (e.g., JavaScript), you should store id as a String. Use the id_str property returned by the API for these values. schema: type: string example: "1489552236571048124" responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/UserRetweetedResponse' '402': description: Payment required - not enough credits to perform this request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested tweet does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. tweet_id or user_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/social-actions/verify-user-retweeted/ /twitter/tweets/{tweet_id}/commented_by/{user_id}: get: tags: - Social Actions API summary: Verify User Commented on a Tweet description: | This endpoint provides a convenient way to check if a user identified by user_id posted a comment in response to a tweet identified by tweet_id. This endpoint only detects direct replies to a target tweet, and not comments posted under other comments. The endpoint returns an array of comment_ids taking into account that a single user may have posted more than a single reply. operationId: verifyTwitterUserCommented parameters: - name: tweet_id in: path required: true description: The numeric ID of the target tweet. When using languages where the id value exceeds the default Integer type limit (e.g., JavaScript), you should store id as a String. Use the id_str property returned by the API for these values. schema: type: string example: 1625802236571033602 - name: user_id in: path required: true description: The numeric ID of the user. When using languages where the id value exceeds the default Integer type limit (e.g., JavaScript), you should store id as a String. Use the id_str property returned by the API for these values. schema: type: string example: 1489552236571048124 responses: '200': description: Request succeeded content: application/json: schema: $ref: '#/components/schemas/UserCommentedResponse' '402': description: Payment required - not enough credits to perform this request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - requested user does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. tweet_id or user_id is not provided or in invalid format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error, typically means that SocialData API failed to obtain the requested information. Retry may succeed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/social-actions/verify-user-commented/ /user/balance: get: tags: - SocialData Account Management summary: Get Remaining Balance description: Returns remaining SocialData balance in USD operationId: getBalance responses: '200': description: Returns remaining balance (USD) content: application/json: schema: type: object properties: balance_usd: type: number format: float example: "123.45" '500': description: API internal error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /user/webhook: post: tags: - Monitoring API - SocialData Account Management summary: Set Global Webhook URL description: Used to set webhook URL that will be used for all monitors that don't have a monitor-specific webhook_url set. operationId: setGlobalWebhook requestBody: required: true content: application/json: schema: type: object properties: url: type: string nullable: true description: New webhook URL that will be used for all monitors that don't have an individual webhook_url set format: uri required: - url example: url: "https://my-website.com/webhook" responses: '200': description: Webhook URL successfully set content: application/json: schema: type: object properties: status: type: string example: "success" message: type: string example: "Webhook URL updated" '422': description: Validation failed (e.g. invalid URL format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/monitoring/set-global-webhook-url/ /user/webhook/secret: post: tags: - Monitoring API - SocialData Account Management summary: Set Webhook Secret description: | Sets the shared secret used to sign every webhook we send you. Your server uses the same value to confirm a request is authentic. You choose the value; there is no generate-a-secret endpoint. Calling this endpoint again replaces the previous secret. The account has one secret, shared by every monitor and every webhook URL. There is no endpoint that returns the current secret - it can only be overwritten. operationId: setWebhookSecret requestBody: required: true content: application/json: schema: type: object properties: secret: type: string maxLength: 256 description: The shared secret used to sign webhook requests. Maximum 256 characters. Store it somewhere your webhook handler can read it, and treat it like a password. required: - secret example: secret: "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" responses: '200': description: Webhook secret successfully set content: application/json: schema: type: object properties: status: type: string example: "success" message: type: string example: "Webhook secret updated" '422': description: Validation failed (e.g. the secret field was not provided) content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' externalDocs: url: https://docs.socialdata.tools/monitoring/set-webhook-secret/ /monitors/user-tweets: post: tags: - Monitoring API summary: Create New User Tweets Monitor description: | Creates a new monitor to receive alerts when the target Twitter user posts a new tweet or makes a retweet. When adding a new monitor SocialData will attempt to fetch user details and return HTTP Status 422 in case the user timeline is protected or user not found. operationId: createUserTweetsMonitor requestBody: required: true content: application/json: schema: type: object properties: user_id: type: string description: User ID of the target user. Required if user_screen_name not provided. example: 1493446837214187523 user_screen_name: type: string description: Username of the target user without @. Required if user_id not provided. example: elonmusk webhook_url: type: string format: uri description: Monitor-specific webhook URL that will override your global webhook URL. Not required. example: https://my-website.com/webhook oneOf: - required: [user_id] - required: [user_screen_name] examples: withUserId: value: user_id: "1493446837214187523" webhook_url: https://my-website.com/webhook withScreenName: value: user_screen_name: elonmusk webhook_url: https://my-website.com/webhook responses: '200': description: Monitor created successfully content: application/json: schema: type: object properties: status: type: string example: "success" data: $ref: '#/components/schemas/Monitor' '402': description: Payment required - not enough credits to perform this request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. user not found or timeline is protected) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/monitoring/create-user-tweets-monitor/ /monitors/user-following: post: tags: - Monitoring API summary: Create Twitter User Following Monitor description: Creates a new monitor to receive alerts when the target Twitter user follows someone. operationId: createUserFollowingMonitor requestBody: required: true content: application/json: schema: type: object properties: user_id: type: string description: User ID of the target user. Required if user_screen_name not provided. example: 1493446837214187523 user_screen_name: type: string description: Username of the target user without @. Required if user_id not provided. example: elonmusk webhook_url: type: string format: uri description: Monitor-specific webhook URL that will override your global webhook URL. Not required. example: https://my-website.com/webhook oneOf: - required: [user_id] - required: [user_screen_name] examples: withUserId: value: user_id: 1493446837214187523 webhook_url: https://my-website.com/webhook withScreenName: value: user_screen_name: elonmusk webhook_url: https://my-website.com/webhook responses: '200': description: Monitor created successfully content: application/json: schema: type: object properties: status: type: string example: "success" data: $ref: '#/components/schemas/Monitor' '402': description: Payment required - not enough credits to perform this request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. user not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/monitoring/create-user-following-monitor/ /monitors/user-profile: post: tags: - Monitoring API summary: Create Twitter User Profile Monitor description: | Creates a new monitor to receive alerts when the target Twitter user changes their profile. Changes in any of the following user profile properties will trigger an event: name, screen_name, location, url, description, profile_banner_url, profile_image_url_https operationId: createUserProfileMonitor requestBody: required: true content: application/json: schema: type: object properties: user_id: type: string description: User ID of the target user. Required if user_screen_name not provided. example: 1493446837214187523 user_screen_name: type: string description: Username of the target user without @. Required if user_id not provided. example: elonmusk webhook_url: type: string format: uri description: Monitor-specific webhook URL that will override your global webhook URL. Not required. example: https://my-website.com/webhook oneOf: - required: [user_id] - required: [user_screen_name] examples: withUserId: value: user_id: 1493446837214187523 webhook_url: https://my-website.com/webhook withScreenName: value: user_screen_name: elonmusk webhook_url: https://my-website.com/webhook responses: '200': description: Monitor created successfully content: application/json: schema: type: object properties: status: type: string example: "success" data: $ref: '#/components/schemas/Monitor' '402': description: Payment required - not enough credits to perform this request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. user not found) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/monitoring/create-user-profile-monitor/ /monitors/search-query: post: tags: - Monitoring API summary: Create New Search Query Monitor description: | Creates a new search query monitor. SocialData will run your monitor every refresh_frequency seconds, retrieve recent search results for query, and dispatch each new matching tweet as an individual webhook event. The first execution delivers nothing - it records which tweets already match your query so that only genuinely new ones are reported afterwards. Each tweet is delivered once. Tweets that are already old when found are skipped; the cutoff is twice your refresh_frequency, or 10 minutes, whichever is longer. Search monitors are billed per delivered tweet and also for each execution that delivers nothing, so refresh_frequency sets your floor cost. operationId: createSearchQueryMonitor requestBody: required: true content: application/json: schema: type: object properties: query: type: string maxLength: 512 description: A UTF-8, URL-encoded search query of up to 512 characters, including any operators supported by Twitter's website search example: from:elonmusk doge refresh_frequency: type: integer minimum: 1 maximum: 3600 default: 30 description: How often the monitor executes, in seconds. This is the main driver of what the monitor costs. example: 300 webhook_url: type: string format: uri description: Monitor-specific webhook URL that will override your global webhook URL. Not required. example: https://my-website.com/webhook required: - query example: query: from:elonmusk doge refresh_frequency: 300 webhook_url: https://my-website.com/webhook responses: '200': description: Monitor created successfully content: application/json: schema: type: object properties: status: type: string example: "success" data: $ref: '#/components/schemas/Monitor' '402': description: Payment required - not enough credits to perform this request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. query was not provided or refresh_frequency is out of range) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/monitoring/create-search-query-monitor/ /monitors: get: tags: - Monitoring API summary: List Active Monitors description: Returns a list of monitors owned by the user. operationId: listMonitors parameters: - name: page in: query required: false description: Page number. schema: type: integer minimum: 1 default: 1 example: 2 - name: per_page in: query required: false description: Monitors returned per page. Values above 50 are capped at 50. schema: type: integer minimum: 1 maximum: 50 default: 25 example: 50 responses: '200': description: List of active monitors retrieved successfully content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Monitor' meta: type: object properties: page: type: integer description: Current page number example: 1 last_page: type: integer description: Total number of pages example: 2 items_count: type: integer description: Total number of monitors example: 100 required: - data - meta example: data: - id: "01jhfkd7xsvy6afdmwycs1qn61" created_at: "2025-01-13T15:30:02.000000Z" monitor_type: "user_following" status: "active" webhook_url: null parameters: user_screen_name: "elonmusk" user_name: "Elon Musk" user_id_str: "44196397" - id: "01jhfkdcmt0d8fjbbxqrtqbmck" created_at: "2025-01-13T15:30:07.000000Z" monitor_type: "user_tweets" status: "paused" webhook_url: null parameters: user_screen_name: "elonmusk" user_name: "Elon Musk" user_id_str: "44196397" - id: "01jqty3m3dhg9xpsj373x12ck7" created_at: "2025-01-13T15:31:22.000000Z" monitor_type: "search_keyword" status: "active" webhook_url: "https://my-website.com/webhook" parameters: query: "from:elonmusk doge" refresh_frequency: 300 meta: page: 1 last_page: 2 items_count: 100 '500': description: API internal error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/monitoring/list-active-monitors/ /monitors/{monitor_id}: get: tags: - Monitoring API summary: Get Monitor Details description: Returns details about a specific monitor. operationId: getMonitorDetails parameters: - name: monitor_id in: path required: true description: Target monitor ID. schema: type: string example: 01jeg76qa91b095gttamsbwa6q responses: '200': description: Request succeeded content: application/json: schema: type: object properties: status: type: string example: "success" data: $ref: '#/components/schemas/Monitor' '404': description: Monitor not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/monitoring/get-monitor-details/ patch: tags: - Monitoring API summary: Edit Monitor Settings description: | Updates a single monitor's settings. You can change its webhook_url and, for search monitors, its refresh_frequency. Updating webhook_url only affects this one monitor and does not change your global webhook URL. When a monitor-specific webhook is not set, all webhook requests will be routed to your global webhook URL. operationId: editMonitorWebhook parameters: - name: monitor_id in: path required: true description: Target monitor ID. schema: type: string example: 01jeg76qa91b095gttamsbwa6q requestBody: required: true content: application/json: schema: type: object properties: webhook_url: type: string nullable: true format: uri description: New webhook URL for this monitor. Pass null to remove the monitor-specific webhook and fall back to your global webhook URL. refresh_frequency: type: integer minimum: 1 maximum: 3600 description: Search monitors only. How often the monitor executes, in seconds. Sending this for any other monitor type returns a validation error. The new frequency takes effect from the monitor's next execution. example: 300 examples: setWebhook: value: webhook_url: "https://my-website.com/webhook" removeWebhook: value: webhook_url: null setRefreshFrequency: value: refresh_frequency: 300 responses: '200': description: Webhook URL successfully updated content: application/json: schema: type: object properties: status: type: string example: "success" data: $ref: '#/components/schemas/Monitor' '404': description: Monitor not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation failed (e.g. invalid URL format) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/monitoring/edit-monitor-webhook/ delete: tags: - Monitoring API summary: Delete Monitor description: Deletes an active monitor. This action stops the API from monitoring new events for the target user profile and halts all future charges associated with this monitor. operationId: deleteMonitor parameters: - name: monitor_id in: path required: true description: Target monitor ID. schema: type: string example: 01jeg76qa91b095gttamsbwa6q responses: '200': description: Monitor successfully deleted content: application/json: schema: type: object properties: status: type: string example: "success" '404': description: Monitor not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: API internal error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/monitoring/delete-monitor/ /monitors/{monitor_id}/events: get: tags: - Monitoring API summary: List Monitor Events description: | Returns the delivery history for a monitor - one entry per webhook request we made, newest first. Use it to find deliveries your server rejected or never received. Reading history costs nothing; these events were already billed when they were detected. operationId: listMonitorEvents parameters: - name: monitor_id in: path required: true description: Target monitor ID. schema: type: string example: 01jeg76qa91b095gttamsbwa6q responses: '200': description: Request succeeded content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/MonitorEvent' required: - data '404': description: Not found - requested monitor does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/monitoring/monitor-event-history/ /monitors/{monitor_id}/events/{event_id}: get: tags: - Monitoring API summary: Get Monitor Event Details description: | Returns a single event, including the full webhook payload we sent and the body your server responded with. The request_body value contains the exact JSON we posted to your webhook URL, so you can parse it to replay the event as if it had been delivered normally. operationId: getMonitorEventDetails parameters: - name: monitor_id in: path required: true description: Target monitor ID. schema: type: string example: 01jeg76qa91b095gttamsbwa6q - name: event_id in: path required: true description: Event ID, as returned in the id field by the list monitor events endpoint. schema: type: string example: MTAwMDAwMDk4NzY1NDMyMQ== responses: '200': description: Request succeeded content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/MonitorEventDetails' required: - data '404': description: Not found - requested monitor or event does not exist content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' externalDocs: url: https://docs.socialdata.tools/monitoring/monitor-event-history/ components: schemas: Tweet: type: object description: Represents a Tweet object with all its properties properties: tweet_created_at: type: string description: The UTC datetime when the tweet was created example: "2023-12-13T05:39:09.000000Z" id: type: integer format: int64 description: The integer representation of the unique identifier for this Tweet. This number is greater than 53 bits and some programming languages may have difficulty/silent defects in interpreting it. Using a signed 64 bit integer for storing this identifier is safe. Use id_str to fetch the identifier to be safe. example: 1050118621198921728 id_str: type: string description: The string representation of the unique identifier for this Tweet. Implementations should use this rather than the large integer in id. example: "1050118621198921728" text: type: string nullable: true description: Deprecated. Always `null` example: null full_text: type: string description: "100 tips I learned growing an iOS app to ~$5M in sales in 3 yrs, going through YC 1.5 times, and co-founding @Superwall 👇" source: type: string description: Utility used to post the Tweet, as an HTML-formatted string. Tweets from the Twitter website have a source value of web. example: "Twitter Web Client" truncated: type: boolean description: Indicates whether the value of the text parameter was truncated, for example, as a result of a retweet exceeding the original Tweet text length limit of 140 characters. Since Twitter now rejects long Tweets vs truncating them, the large majority of Tweets will have this set to false. example: false in_reply_to_status_id: type: integer format: int64 nullable: true description: If the represented Tweet is a reply, this field will contain the integer representation of the original Tweet's ID. example: 1051222721923756032 in_reply_to_status_id_str: type: string nullable: true description: If the represented Tweet is a reply, this field will contain the string representation of the original Tweet's ID. example: "1051222721923756032" in_reply_to_user_id: type: integer format: int64 nullable: true description: If the represented Tweet is a reply, this field will contain the integer representation of the original Tweet's author ID. This will not necessarily always be the user directly mentioned in the Tweet. example: 6253282 in_reply_to_user_id_str: type: string nullable: true description: If the represented Tweet is a reply, this field will contain the string representation of the original Tweet's author ID. This will not necessarily always be the user directly mentioned in the Tweet. example: "6253282" in_reply_to_screen_name: type: string nullable: true description: If the represented Tweet is a reply, this field will contain the screen name of the original Tweet's author. example: "twitterapi" user: allOf: - $ref: '#/components/schemas/User' description: The user who posted this Tweet. lang: type: string description: Nullable. When present, indicates a BCP 47 language identifier corresponding to the machine-detected language of the Tweet text, or und if no language could be detected. example: "en" quoted_status_id: type: integer format: int64 nullable: true description: This field only surfaces when the Tweet is a quote Tweet. This field contains the integer value Tweet ID of the quoted Tweet. example: 1050119905717055488 quoted_status_id_str: type: string nullable: true description: This field only surfaces when the Tweet is a quote Tweet. This is the string representation Tweet ID of the quoted Tweet. example: "1050119905717055488" is_quote_status: type: boolean description: Indicates whether this is a Quoted Tweet. example: false is_pinned: type: boolean description: Indicates if the tweet is pinned to the user's profile. example: false quote_count: type: integer description: Nullable. Indicates approximately how many times this Tweet has been quoted by Twitter users. example: 33 reply_count: type: integer description: Number of times this Tweet has been replied to. example: 30 retweet_count: type: integer description: Number of times this Tweet has been retweeted. example: 160 favorite_count: type: integer description: Nullable. Indicates approximately how many times this Tweet has been liked by Twitter users. example: 295 views_count: type: integer description: Number of views this tweet has received. example: 32377 bookmark_count: type: integer description: Number of times this tweet has been bookmarked. example: 19 quoted_status: type: object allOf: - $ref: '#/components/schemas/Tweet' nullable: true example: null description: This field only surfaces when the Tweet is a quote Tweet. This attribute contains the Tweet object of the original Tweet that was quoted. retweeted_status: type: object allOf: - $ref: '#/components/schemas/Tweet' nullable: true example: null description: Users can amplify the broadcast of Tweets authored by other users by retweeting. Retweets can be distinguished from typical Tweets by the existence of a retweeted_status attribute. This attribute contains a representation of the original Tweet that was retweeted. entities: allOf: - $ref: '#/components/schemas/TweetEntities' description: Entities which have been parsed out of the text of the Tweet such as hashtags, URLs, user mentions, media, and symbols. required: - tweet_created_at - id - id_str - full_text - source - truncated - user - lang - is_quote_status - is_pinned - quote_count - reply_count - retweet_count - favorite_count - views_count - bookmark_count - entities TweetEntities: type: object description: Entities which have been parsed out of the text of the Tweet properties: urls: type: array items: $ref: '#/components/schemas/UrlEntity' user_mentions: type: array items: $ref: '#/components/schemas/UserMentionEntity' hashtags: type: array items: $ref: '#/components/schemas/HashtagEntity' symbols: type: array items: $ref: '#/components/schemas/SymbolEntity' media: type: array items: $ref: '#/components/schemas/MediaEntity' poll: $ref: '#/components/schemas/PollEntity' required: - urls - user_mentions - hashtags - symbols UrlEntity: type: object properties: url: type: string description: Wrapped URL, corresponding to the value embedded directly into the raw Tweet text. expanded_url: type: string description: Expanded version of display_url. display_url: type: string description: URL pasted/typed into Tweet. indices: type: array items: type: integer description: An array of integers representing offsets within the Tweet text where the URL begins and ends. UserMentionEntity: type: object properties: id_str: type: string description: ID of the mentioned user, as a string. name: type: string description: Display name of the referenced user. screen_name: type: string description: Screen name of the referenced user. indices: type: array items: type: integer description: An array of integers representing offsets within the Tweet text where the user mention begins and ends. HashtagEntity: type: object properties: text: type: string description: Name of the hashtag, minus the leading '#' character. indices: type: array items: type: integer description: An array of integers representing offsets within the Tweet text where the hashtag begins and ends. SymbolEntity: type: object properties: text: type: string description: Name of the cashtag, minus the leading '$' character. indices: type: array items: type: integer description: An array of integers representing offsets within the Tweet text where the symbol begins and ends. MediaEntity: type: object properties: id_str: type: string description: ID of the media expressed as a string. media_url_https: type: string description: HTTPS URL pointing directly to the uploaded media file. url: type: string description: Wrapped URL for the media link. display_url: type: string description: URL of the media to display to clients. expanded_url: type: string description: Expanded version of display_url. type: type: string enum: [photo, video, animated_gif] description: Type of uploaded media. indices: type: array items: type: integer description: An array of integers representing offsets within the Tweet text where the media begins and ends. PollEntity: type: object description: Represents a poll attached to a Tweet properties: end_datetime: type: string format: date-time description: The UTC datetime when the poll will end example: "2025-03-12T19:47:12.000000Z" duration_minutes: type: integer description: The duration of the poll in minutes example: 1440 counts_are_final: type: boolean description: Indicates whether the voting period has ended and the results are final example: false choices: type: array description: An array of poll choices minItems: 2 maxItems: 4 items: $ref: '#/components/schemas/PollChoice' required: - end_datetime - duration_minutes - counts_are_final - choices PollChoice: type: object description: Represents a single choice in a poll properties: label: type: string description: The text of the poll choice example: "Yes" count: type: integer description: The number of votes for this choice example: 0 required: - label - count User: type: object description: Twitter user account information properties: id: type: integer format: int64 description: The integer representation of the unique identifier for this User. This number is greater than 53 bits and some programming languages may have difficulty/silent defects in interpreting it. Using a signed 64 bit integer for storing this identifier is safe. Use id_str to fetch the identifier to be safe. example: 6253282 id_str: type: string description: The string representation of the unique identifier for this User. Implementations should use this rather than the large, possibly un-consumable integer in id. example: "6253282" name: type: string description: The name of the user, as they've defined it. Not necessarily a person's name. Typically capped at 50 characters, but subject to change. example: "Twitter API" screen_name: type: string description: The screen name, handle, or alias that this user identifies themselves with. screen_names are unique but subject to change. Use id_str as a user identifier whenever possible. Typically a maximum of 15 characters long, but some historical accounts may exist with longer names. example: "twitterapi" location: type: string description: The user-defined location for this account's profile. Not necessarily a location, nor machine-parseable. This field will occasionally be fuzzily interpreted by the Search service. example: "San Francisco, CA" url: type: string nullable: true description: A URL provided by the user in association with their profile. example: "https://developer.twitter.com" description: type: string description: The user-defined UTF-8 string describing their account. example: "The Real Twitter API." protected: type: boolean description: When true, indicates that this user has chosen to protect their Tweets. example: true verified: type: boolean description: When true, indicates that the user has a verified account with a blue checkmark. example: false followers_count: type: integer description: The number of followers this account currently has. Under certain conditions of duress, this field will temporarily indicate "0". example: 21 friends_count: type: integer description: The number of users this account is following (AKA their "followings"). Under certain conditions of duress, this field will temporarily indicate "0". example: 32 listed_count: type: integer description: The number of public lists that this user is a member of. example: 9274 favourites_count: type: integer description: The number of Tweets this user has liked in the account's lifetime. British spelling used in the field name for historical reasons. example: 13 statuses_count: type: integer description: The number of Tweets (including retweets) issued by the user. example: 42 created_at: type: string description: The UTC datetime that the user account was created on Twitter. example: "2009-06-02T20:12:29.000000Z" profile_banner_url: type: string description: The HTTPS-based URL pointing to the standard web representation of the user's uploaded profile banner. By adding a final path element of the URL, it is possible to obtain different image sizes optimized for specific displays. example: "https://si0.twimg.com/profile_banners/819797/1348102824" profile_image_url_https: type: string description: A HTTPS-based URL pointing to the user's profile image. example: "https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png" can_dm: type: boolean nullable: true description: Indicates whether the authenticated user can send a direct message to this user. example: false required: # - id - id_str - name - screen_name - location - description - protected - verified - followers_count - friends_count - listed_count - favourites_count - statuses_count - created_at - profile_banner_url - profile_image_url_https - can_dm Monitor: type: object description: Represents a monitor configuration properties: id: type: string description: Unique identifier for the monitor example: "01jhfkd7xsvy6afdmwycs1qn61" created_at: type: string format: date-time description: The UTC datetime when the monitor was created example: "2025-01-13T15:30:02.000000Z" monitor_type: type: string enum: - user_tweets - user_following - user_profile - search_keyword description: Type of monitor example: "user_tweets" status: type: string enum: - active - paused description: Whether the monitor is currently checking for updates. A monitor is paused when a charge could not be collected from your balance, and resumes automatically once you top up. example: "active" refresh_frequency: type: integer minimum: 1 maximum: 3600 description: Search monitors only. How often the monitor executes, in seconds. example: 300 webhook_url: type: string nullable: true format: uri description: Monitor-specific webhook URL that overrides the global webhook URL, if set example: null parameters: type: object description: Configuration parameters specific to the type of monitor required: - id - created_at - monitor_type - status - parameters Community: type: object description: A Twitter community properties: id_str: type: string description: The string representation of the unique identifier for this community example: "1493446837214187523" name: type: string example: "Build in Public" description: type: string example: "Share what you're working on. Get feedback. Help each other move forward." created_at: type: string format: date-time example: "2022-02-15T04:47:27.551000Z" creator_screen_name: type: string description: Username of the community creator, without @ example: "marckohlbrugge" creator_is_blue_verified: type: boolean example: true join_policy: type: string example: "Open" rules: type: array description: The community rules, as plain strings items: type: string member_count: type: integer example: 111247 is_nsfw: type: boolean example: false banner_url: type: string nullable: true example: "https://pbs.twimg.com/community_banner_img/1901004865490313216/FVEYARpF?format=png&name=orig" banner_width: type: integer example: 1200 banner_height: type: integer example: 480 required: - id_str - name - member_count ArticleMeta: type: object description: Article metadata, without the article body properties: id: type: integer format: int64 example: 2084992645966016757 id_str: type: string example: "2084992645966016757" title: type: string example: "How to serve 5 models on one GPU (100% open-source)" preview_text: type: string description: The opening of the article, as plain text cover_url: type: string nullable: true example: "https://pbs.twimg.com/media/HO9edfxbEAAxTFy.jpg" published_at: type: string format: date-time example: "2026-08-05T13:19:18.000000Z" required: - id_str - title Article: allOf: - $ref: '#/components/schemas/ArticleMeta' - type: object properties: content_state: type: object description: The article body as X's raw Draft.js document tree - a nested structure of blocks and entity ranges you have to walk yourself. Use the v2 Get Article endpoint if you would rather receive Markdown. media_entities: type: array description: Media referenced from within the article body items: type: object TweetWithArticle: allOf: - $ref: '#/components/schemas/Tweet' - type: object properties: article: type: object allOf: - $ref: '#/components/schemas/Article' nullable: true description: The article attached to this tweet TweetWithMarkdown: allOf: - $ref: '#/components/schemas/Tweet' - type: object properties: markdown: type: string description: The article body rendered as Markdown, or the post's own text rendered as Markdown when markdown_source is tweet_text markdown_source: type: string enum: - article - tweet_text description: Whether the requested ID turned out to be a real article or an ordinary long post. Branch on this rather than assuming. example: article article: type: object allOf: - $ref: '#/components/schemas/ArticleMeta' nullable: true description: Article metadata. Null when markdown_source is tweet_text. Unlike the v1 Get Article endpoint, this object does not contain content_state or media_entities. required: - markdown - markdown_source MonitorEvent: type: object description: One webhook delivery attempt made by a monitor properties: id: type: string description: Event ID, used to fetch the event details example: "MTAwMDAwMDk4NzY1NDMyMQ==" created_at: type: string format: date-time description: The UTC datetime when the delivery was attempted example: "2026-08-01T14:22:31.000000Z" url: type: string format: uri description: The webhook URL the request was sent to example: "https://my-website.com/webhook" response_code: type: integer nullable: true description: The HTTP status your server returned. A null value means the request never completed - a timeout, a DNS failure, or a connection that was refused. example: 200 required: - id - created_at - url - response_code MonitorEventDetails: allOf: - $ref: '#/components/schemas/MonitorEvent' - type: object properties: request_body: type: string description: The exact JSON we posted to your webhook URL. Parse it to replay the event as if it had been delivered normally. response_body: type: string nullable: true description: The body your server responded with required: - request_body ValidationErrorResponse: type: object description: Laravel-style validation error, returned by endpoints that validate individual fields properties: message: type: string example: "The secret field is required." errors: type: object description: One entry per rejected field, each holding an array of messages additionalProperties: type: array items: type: string example: secret: - "The secret field is required." required: - message - errors ErrorResponse: type: object properties: status: type: string enum: [error] message: type: string required: - status - message TweetsResponse: type: object properties: next_cursor: type: string description: Cursor value used to obtain the subsequent page. To be passed to the same endpoint as 'cursor' query parameter. Value may contain spaces and other special characters and therefore must be url-encoded to avoid any errors tweets: type: array items: $ref: '#/components/schemas/Tweet' required: - next_cursor - tweets UsersResponse: type: object properties: next_cursor: type: string description: Cursor value used to obtain the subsequent page. To be passed to the same endpoint as 'cursor' query parameter. Value may contain spaces and other special characters and therefore must be url-encoded to avoid any errors users: type: array items: $ref: '#/components/schemas/User' required: - next_cursor - users UsersWithoutCursorResponse: type: object properties: users: type: array items: $ref: '#/components/schemas/User' required: - users UserFollowingResponse: type: object properties: status: type: string source_user_id: type: string description: The string representation of the unique identifier for follower User. example: "44196397" target_user_id: type: string description: The string representation of the unique identifier for the User being followed. example: "1319287761048723458" is_following: type: boolean description: Indicates whether user identified by source_user_id is following user identified by target_user_id. followers_checked_count: type: integer description: Deprecated. Currently returns 'null' deprecated: true required: - status - source_user_id - target_user_id - is_following - followers_checked_count UserRetweetedResponse: type: object properties: status: type: string source_user_id: type: string description: The string representation of the unique identifier for User. example: "44196397" target_tweet_id: type: string description: The string representation of the unique identifier for the Tweet being retweeted. example: "1319287761048723458" is_retweeted: type: boolean description: Indicates whether user identified by source_user_id has retweeted the Tweet= identified by target_tweet_id. retweeters_checked_count: type: integer description: Deprecated. Currently returns 'null' deprecated: true required: - status - source_user_id - target_tweet_id - is_retweeted - retweeters_checked_count UserCommentedResponse: type: object description: Provides information about whether a user has commented on a specific tweet properties: status: type: string description: Status of the request, "success" when successful example: "success" is_commented: type: boolean description: Indicates whether the user has commented on the target tweet example: true comment_ids: type: array description: List of comment IDs made by the user on the target tweet items: type: string description: The string representation of the unique identifier for the comment example: ["1111111...", "2222222..."] required: - status - is_commented - comment_ids securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: | Each request to SocialData API needs to contain your API key in the Authorization header. Example: `Authorization: Bearer YOUR_API_KEY`