openapi.yml•108 kB
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/search-pump-fun:
post:
tags:
- Monitoring API
summary: Create New Pump.Fun Tweets Monitor
description: |
Creates a new monitor to receive alerts when any profile posts a link to pump.fun coin page. This monitor will only detect tweets that contain links to pump.fun posted by non-shadow-banned Twitter users that have at least 1000 followers.
operationId: createPumpFunMonitor
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
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
example:
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
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-pump-fun-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
- search_pump_fun
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`