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' '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' '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: ids: ["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/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' '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' '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' '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' '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' '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' '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' '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' '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' '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' '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/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' '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' '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' '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' '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/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' '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' '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' '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' '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' '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}/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' '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' '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' '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' '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' '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/ /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: 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. Endpoint returns up to 50 monitors per page. schema: type: integer minimum: 1 default: 1 example: 2 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_followers" webhook_url: null parameters: user_screen_name: "elon_musk" user_name: "Elon Musk" user_id_str: "231198744196397360" - id: "01jhfkdcmt0d8fjbbxqrtqbmck" created_at: "2025-01-13T15:30:07.000000Z" monitor_type: "user_tweets" webhook_url: null parameters: user_screen_name: "elon_musk" user_name: "Elon Musk" user_id_str: "44196397" 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 Webhook URL description: | Used to update or remove a monitor-specific webhook_url. This only updates the webhook URL value associated with a single monitor and does not change your global webhook URL. When 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 monitor-specific webhook. required: - webhook_url examples: setWebhook: value: webhook_url: "https://my-website.com/webhook" removeWebhook: value: webhook_url: null 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/ 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 # 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 # 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 # 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: $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 # 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: $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: $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: $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 # 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 description: Type of monitor example: "user_tweets" 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 - parameters 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`