# SocialData API Documentation
> SocialData API is a scalable and reliable API that simplifies the process of fetching data from social media websites. At the moment, we only support X (formerly Twitter). 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. This ensures a seamless and hassle-free integration with your application, saving you valuable time and effort.
## Getting Started
### Getting Started: Introduction to SocialData API
Source: [Introduction to SocialData API](https://docs.socialdata.tools/getting-started/overview/)
#### Available Endpoints
##### Data API
| | |
| --- | --- |
| Search Endpoints |
| GET [Get Search Results](https://docs.socialdata.tools/reference/get-search-results) | Fetch tweets matching specified search criteria, including keywords, hashtags, and user mentions. Supports all [Twitter Advanced Search operators](https://docs.socialdata.tools/resources/twitter-search-operators) |
| User Endpoints |
| GET [Get User Profile](https://docs.socialdata.tools/reference/get-user-profile) | Retrieve detailed information about a Twitter user’s profile, including bio, follower count, and profile picture |
| GET [Get Multiple User Profiles By Ids](https://docs.socialdata.tools/reference/get-multiple-user-profiles) | Retrieve detailed information about a up to 100 user profiles per request by ids |
| GET [Get Multiple User Profiles By Usernames](https://docs.socialdata.tools/reference/get-multiple-user-profiles-by-usernames) | Retrieve detailed information about a up to 100 user profiles per request by usernames |
| GET [Get User Followers](https://docs.socialdata.tools/reference/get-user-followers) | Retrieve the full list of users who follow the specified account |
| GET [Get User Verified Followers](https://docs.socialdata.tools/reference/get-user-verified-followers) | Retrieve the full list of verified users who follow the specified account |
| GET [Get User Following](https://docs.socialdata.tools/reference/get-user-followings) | Retrieve the full list of users that the specified account is following |
| GET [Get User Tweets](https://docs.socialdata.tools/reference/get-user-tweets-replies) | Retrieve recent tweets or replies posted by the specified user |
| GET [Get User Mentions](https://docs.socialdata.tools/reference/get-user-mentions) | Retrieve all mentions of any user |
| GET [Get User Affiliates](https://docs.socialdata.tools/reference/get-user-affiliates) | Retrieve information about accounts associated with or connected to the specified organization profile |
| GET [Get User Highlights](https://docs.socialdata.tools/reference/get-user-highlights) | Retrieve highlighted tweets from the specified user’s timeline |
| GET [Get User Lists](https://docs.socialdata.tools/reference/get-user-lists) | Retrieve a list of Twitter lists created by or subscribed to by the specified user |
| GET [Get User Extended Bio](https://docs.socialdata.tools/reference/get-user-extended-bio) | Retrieve a user’s extended bio, if available |
| Tweet Endpoints |
| GET [Get Tweet](https://docs.socialdata.tools/reference/get-tweet) | Retrieve complete tweet details together with all embedded media, urls, and complete tweet stats |
| GET [Get Tweet Comments](https://docs.socialdata.tools/reference/get-tweet-comments) | Retrieve comments posted in response to any tweet |
| GET [Get Tweet Quotes](https://docs.socialdata.tools/reference/get-tweet-quotes) | Retrieve quote-tweets posted in response to any tweets |
| GET [Get Tweet Retweeters](https://docs.socialdata.tools/reference/get-tweet-retweeters) | Retrieve the full list of users who have retweeted a specific tweet |
| GET [Get Thread](https://docs.socialdata.tools/reference/get-tweet-thread) | Retrieve all tweets in a conversation thread (i.e. a chain of tweets posted by the same user) |
| GET [Get Article Details](https://docs.socialdata.tools/reference/get-tweet-article) | Retrieve information about an article shared on Twitter, including metadata and engagement statistics |
| List Endpoints |
| GET [Get List Details](https://docs.socialdata.tools/reference/get-list-details) | Retrieve detailed information about a specific Twitter list, including description and member count |
| GET [Get List Members](https://docs.socialdata.tools/reference/get-list-members) | Retrieve a list of users who are members of a specified Twitter list |
| GET [Get List Tweets](https://docs.socialdata.tools/reference/get-list-tweets) | Retrieve tweets published by members of a Twitter list |
| Spaces Endpoints |
| GET [Get Space Details](https://docs.socialdata.tools/reference/get-space-details) | Retrieve information about a specific Twitter Space |
##### Social Actions API
| | |
| --- | --- |
| GET [Verify User Following](https://docs.socialdata.tools/social-actions/verify-user-following) | Check if a specified user is following another user |
| GET [Verify User Retweeted](https://docs.socialdata.tools/social-actions/verify-user-following) | Check whether a user has retweeted a specific tweet |
| GET [Verify User Commented](https://docs.socialdata.tools/social-actions/verify-user-following) | Check if a user has replied to or commented on a particular tweet |
### Getting Started: Pricing
Source: [Pricing](https://docs.socialdata.tools/getting-started/pricing/)
Most of our endpoints follow the same pricing structure - $0.0002 per tweet or user profile returned (or $0.2 per 1000 items)
We also offer volume discounts to our Enterprise customers. If you expect your app to generate a significant volume - please reach out to Support to discuss a custom rate
SocialData API follows a usage-based pricing system, where the exact amount charged against your balance is determined by the amount of data you retrieve.
To access the API, users need to maintain a positive balance in their account, otherwise their request will be rejected with HTTP 402 Payment Required status code.
Each successful request made to our API consumes a certain amount from your balance. The exact charge per request varies depending on the specific API endpoint and the amount of data returned (e.g. if an endpoint returns 20 tweets in one response, each of these tweets will be charged).
On rare occasions our system will fail to retrieve any data from X. Failed requests do not consume any balance, ensuring fair and accurate billing.
#### Price by Endpoint
##### Search Endpoints
| Method | Endpoint | Price |
|--------|----------|-------|
| GET | Get Search Results | $0.0002 per each tweet retrieved |
##### User Endpoints
| Method | Endpoint | Price |
|--------|----------|-------|
| GET | Get User Profile | $0.0002 per request |
| GET | Get Multiple User Profiles By Ids | $0.0002 per each profile |
| GET | Get Multiple User Profiles By Usernames | $0.0002 per each profile |
| GET | Get User Followers | $0.0002 per each follower |
| GET | Get User Verified Followers | $0.0002 per each follower |
| GET | Get User Following | $0.0002 per each followed user |
| GET | Get User Mentions | $0.0002 per each mention |
| GET | Get User Affiliates | $0.0002 per each affiliated user |
| GET | Get User Highlights | $0.0002 per tweet |
| GET | Get User Lists | $0.0002 per list |
| GET | Get User Tweets | $0.0002 per tweet |
| GET | Get User Extended Bio | $0.001 per request |
##### Tweet Endpoints
| Method | Endpoint | Price |
|--------|----------|-------|
| GET | Get Tweet | $0.0002 per request |
| GET | Get Tweet Comments | $0.0002 per each comment |
| GET | Get Tweet Quotes | $0.0002 per each quote-tweet |
| GET | Get Tweet Retweeters | $0.0002 per each user profile |
| GET | Get Thread | $0.0002 per tweet |
| GET | Get Article Details | $0.0002 per request |
##### List Endpoints
| Method | Endpoint | Price |
|--------|----------|-------|
| GET | Get List Details | $0.0002 per request |
| GET | Get List Members | $0.0002 per each list member |
| GET | Get List Tweets | $0.0002 per each tweet |
##### Spaces Endpoints
| Method | Endpoint | Price |
|--------|----------|-------|
| GET | Get Space Details | $0.0002 per request |
##### Social Actions API
| Method | Endpoint | Price |
|--------|----------|-------|
| GET | Verify User Following | $0.004 per request |
| GET | Verify User Retweeted | TBD per request |
| GET | Verify User Commented | TBD per request |
#### Fair-use Policy
By default, requests that do not return any data do not consume any API credits. However, even though these requests are not billed, they still impose a burden on the platform and generate costs.
To provide a certain level of free usage, every account is entitled to make up to 3 requests per minute without incurring any charges. Any requests made beyond the initial 3 free requests per minute will be treated as billable request and incur a fixed charge of $0.0002 per request
### Getting Started: Authentication
Source: [Authentication](https://docs.socialdata.tools/getting-started/authentication/)
#### Summary
- Include your API key as `Authorization: Bearer YOUR_API_KEY` header with all requests
- Each request to SocialData API needs to contain your API key. All unauthenticated requests are rejected.
#### Obtaining Your API Key
To authenticate with the SocialData API, you will need to obtain an API key. This key must be included in the `Authorization: Bearer` header of every HTTP request you make. Follow these steps to get your API key:
1. **Sign Up**: Create an account on the SocialData platform.
2. **API Key**: After signing up, generate your API key in user dashboard. Keep this key confidential, as it is your private access to the API.
#### Using Your API Key
Once you have your API key, you can use it in the Authorization header with the keyword 'Bearer' followed by a space and then your token. Here's an example of what the Authorization header should look like:
```
Authorization: Bearer YOUR_API_KEY
```
Here's a sample cURL request to illustrate how to include the Authorization header in your API calls:
```bash
curl -X GET "https://api.socialdata.tools/twitter/statuses/show?id=1740192018918170738" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_API_KEY"
```
API Keys do not have an expiration date. However you are free to generate a new API key at any moment in your user dashboard.
Do not expose your API Key publicly. Treat it as you would your password, as it grants access to your SocialData API service and budget.
### Getting Started: Rate Limits
Source: [Rate Limits](https://docs.socialdata.tools/getting-started/rate-limits/)
Each user has a limit of 120 requests per minute shared across all endpoints.
We offer higher rate limits at no extra charge if your app is generating a significant volume. Please reach out to [support@socialdata.tools](mailto:support@socialdata.tools) if you need to raise your rate limit.
### Getting Started: Errors
Source: [Errors](https://docs.socialdata.tools/getting-started/errors/)
SocialData uses conventional HTTP response codes to indicate the success or failure of an API request. In general:
- Codes in the 2xx range indicate success.
- Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, Twitter user not found or suspended, etc.).
- Codes in the 5xx range indicate an error with SocialData servers (these are rare) — typically a retry will succeed.
#### HTTP Status Code Summary
| Code | Status | Description |
|------|--------|-------------|
| 200 | OK | Everything worked as expected. |
| 401 | Unauthorized | No valid API key provided. |
| 402 | Payment Required | Credits balance insufficient to process the request, add funds to your balance. |
| 403 | Forbidden | The API key doesn't have permissions to perform the request. |
| 404 | Not Found | The requested resource doesn't exist. |
| 422 | Unprocessable Content | Validation failed. The request was unacceptable, often due to missing a required parameter. |
| 429 | Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. |
| 500 | Server Errors | Something went wrong on SocialData's end (These are rare.) Typically a retry will succeed. |
| 502 | Server Errors | Something went wrong on SocialData's end. (These are rare.) |
| 503 | Server Errors | Something went wrong on SocialData's end. (These are rare.) |
### Getting Started: SDKs & Code Examples
Source: [SDKs & Code Examples](https://docs.socialdata.tools/getting-started/sdks/)
While there are no official SDKs for SocialData API at the moment, there are a number of projects using SocialData that open sourced their implementation.
#### OpenAPI Specification
- [OpenAPI Spec](http://docs.socialdata.tools/openapi.yaml) (updated on Feb 26, 2025)
- [Swagger - OpenAPI spec preview on swagger.io](https://petstore.swagger.io/?url=https://docs.socialdata.tools/openapi.yaml)
#### TypeScript / JavaScript
- [SocialData Client](https://github.com/transitive-bullshit/agentic/blob/main/packages/social-data/src/social-data-client.ts) - client and type definitions included in Agentic by @transitive_bs
- [Twitter Personality](https://github.com/wordware-ai/twitter) by Wordware AI
- [Shiptalkers](https://github.com/RhysSullivan/shiptalkers) by @RhysSullivan
### Getting Started: FAQs & Getting help
Source: [FAQs & Getting help](https://docs.socialdata.tools/getting-started/getting-help/)
We’ve tried to provide the answers to the most common questions in these docs. However, if you need further technical support using SocialData API, you may reach our support team at support@socialdata.tools.
## Data API
### Data API: Get Search Results
Source: [Get Search Results - API Reference](https://docs.socialdata.tools/reference/get-search-results/)
Returns array of tweets provided by Twitter search page. Typically Twitter returns ~20 results per page. You can request additional search results by sending another request to the same endpoint using cursor parameter.
Endpoint: GET https://api.socialdata.tools/twitter/search?query={query}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| query | string | required | A UTF-8, URL-encoded search query, including any operators supported by Twitter website search
Example: `from:elonmusk doge` |
| cursor | string | optional | Cursor value obtained from next_cursor response property. Used to retrieve additional pages for the same query
Example: `DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0d...` |
| type | enum | optional | Search type (Latest for recent tweets or Top for popular tweets). Default - Latest
Example: `Top` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/search?query=from%3Aelonmusk&type=Latest"
-H 'Authorization: Bearer YOUR_API_KEY'
-H 'Accept: application/json'
```
```python
import requests
query = 'from:elonmusk -filter:replies since_id:1869986946031988780'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/search?query={requests.utils.quote(query)}&type=Latest'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```javascript
const query = 'from:elonmusk -filter:replies since_id:1869986946031988780';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/search?query=${encodeURIComponent(query)}&type=Latest`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```php
$query = 'from:elonmusk -filter:replies since_id:1869986946031988780';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/search?query=" . urlencode($query) . "&type=Latest";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"next_cursor": "DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0dKTjB2R3AvQUFBQUJNWUxTNkQyQmFoUXhndFRReS9Ga0NOR0MwZG9yS1hzU2NZTFFwYm0xY1I0aGd0YmhZc1drQ3FHQzBjUXNSV1lSZ1lMVml5V3BxQU9CZ3RMbUhUV2tDb0dDMVFuVW1YMEFzWUxKYURhOVpob3hndFZtaklGakNNR0MxWGdlT1dZSE1ZTFRYNFNwZUEraGd0Y2h2bEYxRkxHQzFNMi83V1VGc1lMTTZwemhZQWt4Z3RWMkJKbDNGN0dDMWFGTXBYUUY4WUxUUERuRlp3UVE9PQgABgAAAAAIAAcAAAAADAAICgABGCyWg2vWYaMAAAA",
"tweets": [
{
"tweet_created_at": "2023-12-13T05:39:09.000000Z",
"id_str": "1734810168053956719",
"text": null,
"full_text": "@TeslaHype Pace of Progress",
"source": "Twitter for iPhone<\\/a>",
"truncated": false,
"in_reply_to_status_id_str": "1734777084268920960",
"in_reply_to_user_id_str": "1311506622821400581",
"in_reply_to_screen_name": "TeslaHype",
"user": {
"id_str": "44196397",
"name": "Elon Musk",
"screen_name": "elonmusk",
"location": "\\ud835\\udd4f\\u00d0",
"url": null,
"description": "",
"protected": false,
"verified": false,
"followers_count": 166213349,
"friends_count": 506,
"listed_count": 149586,
"favourites_count": 37958,
"statuses_count": 34934,
"created_at": "2009-06-02T20:12:29.000000Z",
"profile_banner_url": "https:\\/\\/pbs.twimg.com\\/profile_banners\\/44196397\\/1690621312",
"profile_image_url_https": "https:\\/\\/pbs.twimg.com\\/profile_images\\/1683325380441128960\\/yRsRRjGO_normal.jpg",
"can_dm": false
},
"quoted_status_id_str": null,
"is_quote_status": false,
"quoted_status": null,
"retweeted_status": null,
"quote_count": 11,
"reply_count": 156,
"retweet_count": 78,
"favorite_count": 977,
"lang": "en",
"entities": {
"user_mentions": [
{
"id_str": "1311506622821400581",
"name": "Tesla Hype",
"screen_name": "TeslaHype",
"indices": [
0,
10
]
}
],
"urls": [],
"hashtags": [],
"symbols": []
},
"views_count": 32377,
"bookmark_count": 19
},
{
"tweet_created_at": "2023-12-13T05:38:26.000000Z",
"id_str": "1734809984674693446",
"text": null,
"full_text": "@anammostarac Yeah",
"source": "Twitter for iPhone<\\/a>",
"truncated": false,
"in_reply_to_status_id_str": "1734809562258276654",
"in_reply_to_user_id_str": "2852570664",
"in_reply_to_screen_name": "anammostarac",
"user": {
"id_str": "44196397",
"name": "Elon Musk",
"screen_name": "elonmusk",
"location": "\\ud835\\udd4f\\u00d0",
"url": null,
"description": "",
"protected": false,
"verified": false,
"followers_count": 166213349,
"friends_count": 506,
"listed_count": 149586,
"favourites_count": 37958,
"statuses_count": 34934,
"created_at": "2009-06-02T20:12:29.000000Z",
"profile_banner_url": "https:\\/\\/pbs.twimg.com\\/profile_banners\\/44196397\\/1690621312",
"profile_image_url_https": "https:\\/\\/pbs.twimg.com\\/profile_images\\/1683325380441128960\\/yRsRRjGO_normal.jpg",
"can_dm": false
},
"quoted_status_id_str": null,
"is_quote_status": false,
"quoted_status": null,
"retweeted_status": null,
"quote_count": 4,
"reply_count": 64,
"retweet_count": 30,
"favorite_count": 513,
"lang": "en",
"entities": {
"user_mentions": [
{
"id_str": "2852570664",
"name": "Ana Mostarac",
"screen_name": "anammostarac",
"indices": [
0,
13
]
}
],
"urls": [],
"hashtags": [],
"symbols": []
},
"views_count": 25579,
"bookmark_count": 3
}
]
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Using Search Operators
Caution: All search operators must be included as part of your `?query=` parameter and not as separate endpoint parameters.
For example, the following query will return tweets by Elon Musk, containing "keyword", and posted after a specific timestamp:
```
keyword from:elonmusk since_time:1738381166
```
This endpoint supports all search operators supported by Twitter. Search operators must be included as part of query parameter and not as separate endpoint parameters.
#### Some frequently used search operators:
- `@USERNAME -from:USERNAME` — will return all mentions of @username
- `from:USERNAME` — will return all tweets and replies made by user
- `from:USERNAME filter:replies` — will return only replies, but not tweets
- `from:USERNAME -filter:replies` — will return only tweets, but not replies
- `since_time:TIMESTAMP` and `until_time:TIMESTAMP` — will return tweets and comments posted after or before the provided UNIX timestamp
- `since_id:TWEET_ID` and `max_id:TWEET_ID` — will return tweets with ID higher or lower than the provided TWEET_ID
- `conversation_id:TWEET_ID` — will return all comments posted in response to TWEET_ID
For a more detailed overview of Twitter search operators refer to the [following page](https://docs.socialdata.tools/resources/twitter-search-operators/)
#### Known Limitations
Twitter removes tweets flagged as spam, or all tweets from all shadow-banned users. Request to retrieve tweets or comments made by a shadow-banned user (i.e. `from:USERNAME`) will always return 0 tweets, but the user's timeline is still available through User tweets and replies endpoint.
#### Retrieving Large Datasets
Occasionally when you need to scrape a large number of tweets, Twitter eventually refuses to provide additional cursor values after scraping too many page with "Latest" search filter. As a workaround, it is possible to cycle through a larger dataset using `max_id:` and `since_id:` search operators.
When retrieving "Latest" search results, Twitter provides the response with tweets sorted by ID in descending order. If you need to retrieve more posts - simply make another request with the same query adding `max_id:[lowest ID from current dataset]`. Using this approach it is possible to extract the entire timeline from the moment an account was registered.
### Data API: Get User Profile
Source: [Get User Profile - API Reference](https://docs.socialdata.tools/reference/get-user-profile/)
Retrieve user information by their Twitter ID or screen name.
Endpoint: GET https://api.socialdata.tools/twitter/user/{user_id}
Endpoint: GET https://api.socialdata.tools/twitter/user/{username}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| user_id | integer | required | The numerical id of the target user profile. Either a user_id or username is required for this endpoint.
Example: `44196397` |
| username | string | required | Username of the target user profile without @. Either a user_id or username is required for this endpoint.
Example: `elonmusk` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/user/elonmusk"
-H 'Authorization: Bearer YOUR_API_KEY'
-H 'Accept: application/json'
# OR
curl "https://api.socialdata.tools/twitter/user/343990983"
-H 'Authorization: Bearer YOUR_API_KEY'
-H 'Accept: application/json'
```
```python
import requests
username = 'elonmusk'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/user/{username}'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```javascript
const username = 'elonmusk';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/user/${username}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```php
$username = 'elonmusk';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/user/{$username}";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
// Example response
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Data API: Get Multiple User Profiles By Ids
Source: [Get Multiple User Profiles By Ids - API Reference](https://docs.socialdata.tools/reference/get-multiple-user-profiles/)
Retrieve user information for up to 100 users per request.
Endpoint: POST https://api.socialdata.tools/twitter/users-by-id
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Body
| Name | Type | Required | Description |
|------|------|----------|-------------|
| ids | array | required | An array of Twitter user ids. Up to 100 ids per request
Example: `[44196397, 1319287761048723458, ...]` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/users-by-id" \
-X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"ids": [44196397, 1319287761048723458]}'
```
```javascript
const ids = ["44196397", "1319287761048723458"];
const API_KEY = 'YOUR_API_KEY';
fetch('https://api.socialdata.tools/twitter/users-by-id', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
'Accept': 'application/json'
},
body: JSON.stringify({ ids })
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
ids = [44196397, 1319287761048723458]
API_KEY = 'YOUR_API_KEY'
url = 'https://api.socialdata.tools/twitter/users-by-id'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
payload = {'ids': ids}
response = requests.post(url, json=payload, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$ids = [44196397, 1319287761048723458];
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/users-by-id";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode(['ids' => $ids]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Content-Type: application/json",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"users": [
{
"id": 44196397,
"id_str": "44196397",
"name": "Elon Musk",
"screen_name": "elonmusk",
"location": "\\ud835\\udd4f\\u00d0",
"url": null,
"description": "",
"protected": false,
"verified": true,
"followers_count": 166213974,
"friends_count": 506,
"listed_count": 149577,
"favourites_count": 37987,
"statuses_count": 34934,
"created_at": "2009-06-02T20:12:29.000000Z",
"profile_banner_url": "https:\\/\\/pbs.twimg.com\\/profile_banners\\/44196397\\/1690621312",
"profile_image_url_https": "https:\\/\\/pbs.twimg.com\\/profile_images\\/1683325380441128960\\/yRsRRjGO_normal.jpg",
"can_dm": false
},
// ...
]
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Data API: Get Multiple User Profiles By Usernames
Source: [Get Multiple User Profiles By Usernames - API Reference](https://docs.socialdata.tools/reference/get-multiple-user-profiles-by-usernames/)
Retrieve user information for up to 100 users per request.
Endpoint: POST https://api.socialdata.tools/twitter/users-by-usernames
#### Caution
Due to limitations in our data source, this endpoint cannot provide accurate values for the "verified" and "can_dm" attributes. We recommend using the "users-by-ids" endpoint instead for more reliable results.
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Body
| Name | Type | Required | Description |
|------|------|----------|-------------|
| usernames | array | required | An array of Twitter usernames. Up to 100 usernames per request
Example: `["elonmusk", "realdonaldtrump", ...]` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/users-by-usernames" \
-X POST \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"usernames": ["elonmusk", "realdonaldtrump"]}'
```
```javascript
const usernames = ["elonmusk", "realdonaldtrump"];
const API_KEY = 'YOUR_API_KEY_HERE';
fetch('https://api.socialdata.tools/twitter/users-by-usernames', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
'Accept': 'application/json'
},
body: JSON.stringify({ usernames })
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
usernames = ['elonmusk', 'realdonaldtrump']
API_KEY = 'YOUR_API_KEY_HERE'
url = 'https://api.socialdata.tools/twitter/users-by-usernames'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
payload = {'usernames': usernames}
response = requests.post(url, json=payload, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$usernames = ["elonmusk", "realdonaldtrump"];
$API_KEY = 'YOUR_API_KEY_HERE';
$url = "https://api.socialdata.tools/twitter/users-by-usernames";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode(['usernames' => $usernames]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Content-Type: application/json",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"users": [
{
"id": 44196397,
"id_str": "44196397",
"name": "Elon Musk",
"screen_name": "elonmusk",
"location": "\\ud835\\udd4f\\u00d0",
"url": null,
"description": "",
"protected": false,
"verified": false, // This endpoint is unable to provide correct Blue-checkmark verified status. Please use users-by-ids instead
"followers_count": 166213974,
"friends_count": 506,
"listed_count": 149577,
"favourites_count": 37987,
"statuses_count": 34934,
"created_at": "2009-06-02T20:12:29.000000Z",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/44196397/1690621312",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1683325380441128960/yRsRRjGO_normal.jpg",
"can_dm": null // This endpoint is unable to provide correct can_dm value. Please use users-by-ids instead
},
// ...
]
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
### Data API: Get User Affiliates
Source: [Get User Affiliates - API Reference](https://docs.socialdata.tools/reference/get-user-affiliates/)
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.
Endpoint: GET https://api.socialdata.tools/twitter/user/{user_id}/affiliates?cursor={cursor}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| user_id | integer | required | The numeric ID of the desired user.
Example: `1729591119699124560` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| cursor | string | optional | Cursor value obtained from next_cursor response property. Omit this value to retrieve the first page. Always remember to urlendode the value
Example: `DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0d...` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/user/783214/affiliates" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const userId = '783214';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/user/${userId}/affiliates`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
userId = '783214'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/user/{userId}/affiliates'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$userId = '783214';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/user/{$userId}/affiliates";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"users": [
{
"id": 1076061,
"id_str": "1076061",
"name": "Keith Coleman 🌱😀🙌",
"screen_name": "kcoleman",
"location": "San Francisco, CA",
"url": null,
"description": "VP Product @X. Previously CEO at Yes Inc, @google 🙌",
"protected": false,
"verified": true,
"followers_count": 30521,
"friends_count": 825,
"listed_count": 334,
"favourites_count": 14063,
"statuses_count": 2734,
"created_at": "2007-03-13T08:18:45.000000Z",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1076061/1478574872",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1093367487566012416/9Wc1J-Pk_normal.jpg",
"can_dm": true
},
// ...
],
"next_cursor": "DAAHCgABGPytdBi__-wLAAIAAAAIMTUxMzM0ODEIAAMAAAACAAA"
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested user not found
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Data API: Get User Highlighted Tweets
Source: [Get User Highlighted Tweets - API Reference](https://docs.socialdata.tools/reference/get-user-highlights/)
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.
Endpoint: GET https://api.socialdata.tools/twitter/user/{user_id}/highlights?cursor={cursor}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| user_id | integer | required | The numeric ID of the desired user.
Example: `1729591119699124560` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| cursor | string | optional | Cursor value obtained from next_cursor response property. Omit this value to retrieve the first page. Always remember to urlendode the value
Example: `DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0d...` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/user/44196397/highlights" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const userId = '44196397';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/user/${userId}/highlights`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
userId = '44196397'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/user/{userId}/highlights'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$userId = '44196397';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/user/{$userId}/highlights";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"next_cursor": "DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0dKTjB2R3AvQUFBQUJNWUxTNkQyQmFoUXhndFRReS9Ga0NOR0MwZG9yS1hzU2NZTFFwYm0xY1I0aGd0YmhZc1drQ3FHQzBjUXNSV1lSZ1lMVml5V3BxQU9CZ3RMbUhUV2tDb0dDMVFuVW1YMEFzWUxKYURhOVpob3hndFZtaklGakNNR0MxWGdlT1dZSE1ZTFRYNFNwZUEraGd0Y2h2bEYxRkxHQzFNMi83V1VGc1lMTTZwemhZQWt4Z3RWMkJKbDNGN0dDMWFGTXBYUUY4WUxUUERuRlp3UVE9PQgABgAAAAAIAAcAAAAADAAICgABGCyWg2vWYaMAAAA",
"tweets": [
{
"tweet_created_at": "2024-05-15T22:33:29.000000Z",
"id": 1790873164374810919,
"id_str": "1790873164374810919",
"text": null,
"full_text": "https://t.co/mS960WQX4Y",
"source": "Twitter Web App",
"truncated": false,
"in_reply_to_status_id": null,
"in_reply_to_status_id_str": null,
"in_reply_to_user_id": null,
"in_reply_to_user_id_str": null,
"in_reply_to_screen_name": null,
"user": {
"id": 783214,
"id_str": "783214",
"name": "X",
"screen_name": "X",
"location": "everywhere",
"url": "https://about.x.com/",
"description": "what's happening?!",
"protected": false,
"verified": true,
"followers_count": 67739714,
"friends_count": 0,
"listed_count": 88755,
"favourites_count": 5892,
"statuses_count": 15327,
"created_at": "2007-02-20T14:35:54.000000Z",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/783214/1690175171",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1683899100922511378/5lY42eHs_normal.jpg",
"can_dm": false
}
},
// ...
]
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested user not found
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Data API: Get User's Twitter Likes
Source: [Get User's Twitter Likes - API Reference](https://docs.socialdata.tools/reference/get-user-likes/)
Deprecated
Due to Twitter’s decision to make likes private for all users, this endpoint is unable to provide any data.
### Data API: Get User's Lists
Source: [Get User's Lists - API Reference](https://docs.socialdata.tools/reference/get-user-lists/)
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.
Endpoint: GET https://api.socialdata.tools/twitter/user/{user_id}/lists?cursor={cursor}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| user_id | integer | required | The numeric ID of the desired user.
Example: `1729591119699124560` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| cursor | string | optional | Cursor value obtained from next_cursor response property. Omit this value to retrieve the first page. Always remember to urlendode the value
Example: `DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0d...` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/user/44196397/lists" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const userId = '44196397';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/user/${userId}/lists`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
userId = '44196397'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/user/{userId}/lists'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$userId = '44196397';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/user/{$userId}/lists";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"next_cursor": "1545854927532064769|1752635769203195807",
"lists": [
{
"created_at": 1668221936000,
"default_banner_media": {
"media_info": {
"original_img_url": "https://pbs.twimg.com/media/EXZ2mJCUEAEbJb3.png",
"original_img_width": 1125,
"original_img_height": 375,
"salient_rect": {
"left": 562,
"top": 187,
"width": 1,
"height": 1
}
}
},
"default_banner_media_results": {
"result": {
"id": "QXBpTWVkaWE6DAABCgABEXZ2mJCUEAEKAAIQF4A+eBQgAAAA",
"media_key": "3_1258323543529361409",
"media_id": "1258323543529361409",
"media_info": {
"__typename": "ApiImage",
"original_img_height": 375,
"original_img_width": 1125,
"original_img_url": "https://pbs.twimg.com/media/EXZ2mJCUEAEbJb3.png",
"salient_rect": {
"height": 1,
"left": 562,
"top": 187,
"width": 1
}
},
"__typename": "ApiMedia"
}
},
"description": "",
"facepile_urls": [
"https://pbs.twimg.com/profile_images/1201525049766883328/QPimCC9z_mini.jpg",
"https://pbs.twimg.com/profile_images/1603461568708153346/plKcInwe_mini.jpg",
"https://pbs.twimg.com/profile_images/1598855439076425728/q5FlqPZU_mini.jpg"
],
"followers_context": "16 followers including @arvidkahl",
"following": false,
"id": "TGlzdDoxNTkxMjY0MjUxMzMwNDI4OTI5",
"id_str": "1591264251330428929",
"is_member": false,
"member_count": 85,
"members_context": "85 members",
"mode": "Public",
"muting": false,
"name": "🌟 Creators 🔥",
"pinning": false,
"subscriber_count": 16,
"user_results": {
"result": {
"__typename": "User",
"id": "VXNlcjoyOTA0MjE5Njcz",
"rest_id": "2904219673",
"affiliates_highlighted_label": [],
"has_graduated_access": true,
"is_blue_verified": true,
"profile_image_shape": "Circle",
"legacy": {
"can_dm": false,
"can_media_tag": true,
"created_at": "Wed Nov 19 05:35:32 +0000 2014",
"default_profile": false,
"default_profile_image": false,
"description": "Helping digital creators save 20+ hours a month. Leverage AI/Automation for content repurposing and distribution. Saved clients over 10,000+ hours",
"entities": {
"description": {
"urls": []
},
"url": {
"urls": [
{
"display_url": "hiddenlevers.ai/subscribe?utm_…",
"expanded_url": "https://www.hiddenlevers.ai/subscribe?utm_source=twitter&utm_medium=bio",
"url": "https://t.co/ykaoNAJGQD",
"indices": [
0,
23
]
}
]
}
},
"fast_followers_count": 0,
"favourites_count": 46302,
"followers_count": 7948,
"friends_count": 1722,
"has_custom_timelines": true,
"is_translator": false,
"listed_count": 234,
"location": "Amplify Your Impact 👇🏼",
"media_count": 2938,
"name": "Mike Cardona | Automation Alchemist 🧪🔧",
"normal_followers_count": 7948,
"pinned_tweet_ids_str": [
"1699665975136878643"
],
"possibly_sensitive": false,
"profile_banner_url": "https://pbs.twimg.com/profile_banners/2904219673/1704725393",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1566400585137414145/vkBaB3ca_normal.jpg",
"profile_interstitial_type": "",
"screen_name": "CSMikeCardona",
"statuses_count": 27559,
"translator_type": "none",
"url": "https://t.co/ykaoNAJGQD",
"verified": false,
"want_retweets": false,
"withheld_in_countries": []
},
"professional": {
"rest_id": "1459282952534196228",
"professional_type": "Creator",
"category": []
}
}
}
},
// ...
]
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested user not found
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Data API: Get User's Tweets and Replies
Source: [Get User's Tweets and Replies - API Reference](https://docs.socialdata.tools/reference/get-user-tweets-replies/)
Returns array of tweets from the user's tweets and replies 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.
#### Tip
This endpoint doesn't support any filters and we can't adjust the number of items returned in the response. To have more flexibility - you may also use the Search endpoint with from:USERNAME query to retrieve the user's timeline. Our advanced search endpoint supports all of Twitter's search operators
#### Endpoint
To request only user's tweets timeline:
```
GET https://api.socialdata.tools/twitter/user/{user_id}/tweets?cursor={cursor}
```
To request only user's replies timeline (this will also include own tweets):
```
GET https://api.socialdata.tools/twitter/user/{user_id}/tweets-and-replies?cursor={cursor}
```
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| user_id | integer | required | The numerical ID of the desired user
Example: `443198458` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| cursor | string | optional | Cursor value obtained from next_cursor response property. Omit this value to retrieve the first page. Always remember to urlendode the value
Example: `DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0d...` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/user/44196397/tweets" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const userId = '1729591119699124560';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/user/${userId}/tweets`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
userId = '1729591119699124560'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/user/{userId}/tweets'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$userId = '1729591119699124560';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/user/{$userId}/tweets";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"next_cursor": "DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0dKTjB2R3AvQUFBQUJNWUxTNkQyQmFoUXhndFRReS9Ga0NOR0MwZG9yS1hzU2NZTFFwYm0xY1I0aGd0YmhZc1drQ3FHQzBjUXNSV1lSZ1lMVml5V3BxQU9CZ3RMbUhUV2tDb0dDMVFuVW1YMEFzWUxKYURhOVpob3hndFZtaklGakNNR0MxWGdlT1dZSE1ZTFRYNFNwZUEraGd0Y2h2bEYxRkxHQzFNMi83V1VGc1lMTTZwemhZQWt4Z3RWMkJKbDNGN0dDMWFGTXBYUUY4WUxUUERuRlp3UVE9PQgABgAAAAAIAAcAAAAADAAICgABGCyWg2vWYaMAAAA",
"tweets": [
{
"tweet_created_at": "2023-12-13T05:39:09.000000Z",
"id_str": "1734810168053956719",
"text": null,
"full_text": "@TeslaHype Pace of Progress",
"source": "Twitter for iPhone",
"truncated": false,
"in_reply_to_status_id_str": "1734777084268920960",
"in_reply_to_user_id_str": "1311506622821400581",
"in_reply_to_screen_name": "TeslaHype",
"user": {
"id_str": "44196397",
"name": "Elon Musk",
"screen_name": "elonmusk",
"location": "𝕏",
"url": null,
"description": "",
"protected": false,
"verified": false,
"followers_count": 166213349,
"friends_count": 506,
"listed_count": 149586,
"favourites_count": 37958,
"statuses_count": 34934,
"created_at": "2009-06-02T20:12:29.000000Z",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/44196397/1690621312",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1683325380441128960/yRsRRjGO_normal.jpg",
"can_dm": false
},
"quoted_status_id_str": null,
"is_quote_status": false,
"quoted_status": null,
"retweeted_status": null,
"quote_count": 11,
"reply_count": 156,
"retweet_count": 78,
"favorite_count": 977,
"lang": "en",
"entities": {
"user_mentions": [
{
"id_str": "1311506622821400581",
"name": "Tesla Hype",
"screen_name": "TeslaHype",
"indices": [
0,
10
]
}
],
"urls": [],
"hashtags": [],
"symbols": []
},
"views_count": 32377,
"bookmark_count": 19
},
// ... more tweets
]
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested user not found
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Data API: Get User Followers
Source: [Get User Followers - API Reference](https://docs.socialdata.tools/reference/get-user-followers/)
This endpoint 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.
Endpoint: GET https://api.socialdata.tools/twitter/followers/list?user_id={user_id}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| user_id | integer | required | The numeric ID of the desired user.
Example: `1625802236571033602` |
| cursor | string | optional | Cursor value obtained from next_cursor response property. Omit this value to retrieve the first page
Example: `4611686018541662731|1741085517660815316` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/followers/list?user_id=44196397" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const userId = '44196397';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/followers/list?user_id=${userId}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
userId = '44196397'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/followers/list?user_id={userId}'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$userId = '44196397';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/followers/list?user_id={$userId}";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"next_cursor": "4611686018541662731|1741080922217775060",
"users": [
{
"id": 1547124452596523008,
"id_str": "1547124452596523008",
"name": "Gwendal Brossard",
"screen_name": "GwendalBrossard",
"location": "Building",
"url": "https://t.co/6o4TTYu7LQ",
"description": "I'm an indie maker building products 👨💻 @PaletteBrain─https://t.co/BEadk6UDlz ✨",
"protected": false,
"verified": false,
"followers_count": 3557,
"friends_count": 149,
"listed_count": 41,
"favourites_count": 12425,
"statuses_count": 6778,
"created_at": "2022-07-13T07:43:56.000000Z",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1547124452596523008/1672736091",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1572151372455313409/qq1yH56d_normal.jpg",
"can_dm": true
},
// ...
]
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested user not found
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Data API: Get User Verified Followers
Source: [Get User Verified Followers - API Reference](https://docs.socialdata.tools/reference/get-user-verified-followers/)
This endpoint 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.
Endpoint: GET https://api.socialdata.tools/twitter/user/{user_id}/verified-followers?cursor={cursor}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| user_id | integer | required | The numeric ID of the desired user.
Example: `1625802236571033602` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| cursor | string | optional | Cursor value obtained from next_cursor response property. Omit this value to retrieve the first page
Example: `4611686018541662731|1741085517660815316` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/user/44196397/verified-followers" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const userId = '44196397';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/user/${userId}/verified-followers`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
userId = '44196397'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/user/{userId}/verified-followers'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$userId = '44196397';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/user/{$userId}/verified-followers";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"next_cursor": "4611686018541662731|1741080922217775060",
"users": [
{
"id": 1547124452596523008,
"id_str": "1547124452596523008",
"name": "Gwendal Brossard",
"screen_name": "GwendalBrossard",
"location": "Building",
"url": "https://t.co/6o4TTYu7LQ",
"description": "I'm an indie maker building products 👨💻 @PaletteBrain─https://t.co/BEadk6UDlz ✨",
"protected": false,
"verified": true,
"followers_count": 3557,
"friends_count": 149,
"listed_count": 41,
"favourites_count": 12425,
"statuses_count": 6778,
"created_at": "2022-07-13T07:43:56.000000Z",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1547124452596523008/1672736091",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1572151372455313409/qq1yH56d_normal.jpg",
"can_dm": true
},
// ...
]
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested user not found
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Data API: Get User Following List
Source: [Get User Following List - API Reference](https://docs.socialdata.tools/reference/get-user-followings/)
This endpoint 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.
Endpoint: GET https://api.socialdata.tools/twitter/friends/list?user_id={user_id}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| user_id | integer | required | The numeric ID of the desired user.
Example: `1729591119699124560` |
| cursor | string | optional | Cursor value obtained from next_cursor response property. Omit this value to retrieve the first page
Example: `4611686018541662731|1741085517660815316` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/friends/list?user_id=44196397" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const userId = '44196397';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/friends/list?user_id=${userId}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
userId = '44196397'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/friends/list?user_id={userId}'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$userId = '44196397';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/friends/list?user_id={$userId}";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"next_cursor": "4611686018541662731|1741080922217775060",
"users": [
{
"id": 1547124452596523008,
"id_str": "1547124452596523008",
"name": "Gwendal Brossard",
"screen_name": "GwendalBrossard",
"location": "Building",
"url": "https://t.co/6o4TTYu7LQ",
"description": "I'm an indie maker building products 👨💻 @PaletteBrain─https://t.co/BEadk6UDlz ✨",
"protected": false,
"verified": false,
"followers_count": 3557,
"friends_count": 149,
"listed_count": 41,
"favourites_count": 12425,
"statuses_count": 6778,
"created_at": "2022-07-13T07:43:56.000000Z",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1547124452596523008/1672736091",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1572151372455313409/qq1yH56d_normal.jpg",
"can_dm": true
},
// ...
]
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested user not found
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Data API: Get User's Extended Twitter Bio
Source: [Get User's Extended Twitter Bio - API Reference](https://docs.socialdata.tools/reference/get-user-extended-bio/)
Returns an object with user's extended bio with all text and formatting details, or an empty object if the extended bio is missing
Endpoint: GET https://api.socialdata.tools/twitter/user/{username}/extended-bio
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| username | string | required | Username of the target user profile without @.
Example: `elonmusk` |
#### Example Responses
```json
{
"blocks": [
{
"text": "I took my 𝕏 (Twitter) account from 0 to 5.5 million impressions in less than 3 months and over 11 million impressions in 5 months using a combination of memes and satirical posts.",
"type": "unstyled",
"inlineStyleRanges": [],
"entityRanges": [],
"depth": 0,
"key": "8v159"
},
// ... more blocks
],
"entityMap": []
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested user not found
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
### Data API: Get User Mentions
Source: [Get User Mentions - API Reference](https://docs.socialdata.tools/reference/get-user-mentions/)
Retrieve user information by their Twitter ID or screen name.
Endpoint: GET https://api.socialdata.tools/twitter/user/{username}/mentions?cursor={cursor}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| username | string | required | Username of the target user profile without @. Either a user_id or username is required for this endpoint.
Example: `elonmusk` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| cursor | string | optional | Cursor value obtained from next_cursor response property. Used to retrieve additional pages for the same query
Example: `1890084840239985036` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/user/elonmusk/mentions" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const username = 'elonmusk';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/user/${username}/mentions`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
username = 'elonmusk'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/user/{username}/mentions'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$username = 'elonmusk';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/user/{$username}/mentions";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"next_cursor": "1890084840239985036",
"tweets": [
{
"tweet_created_at": "2023-12-13T05:39:09.000000Z",
"id_str": "1734810168053956719",
"text": null,
"full_text": "@TeslaHype Pace of Progress",
"source": "Twitter for iPhone",
"truncated": false,
"in_reply_to_status_id_str": "1734777084268920960",
"in_reply_to_user_id_str": "1311506622821400581",
"in_reply_to_screen_name": "TeslaHype",
"user": {
"id_str": "44196397",
"name": "Elon Musk",
"screen_name": "elonmusk",
"location": "𝕏",
"url": null,
"description": "",
"protected": false,
"verified": false,
"followers_count": 166213349,
"friends_count": 506,
"listed_count": 149586,
"favourites_count": 37958,
"statuses_count": 34934,
"created_at": "2009-06-02T20:12:29.000000Z",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/44196397/1690621312",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1683325380441128960/yRsRRjGO_normal.jpg",
"can_dm": false
},
"quoted_status_id_str": null,
"is_quote_status": false,
"quoted_status": null,
"retweeted_status": null,
"quote_count": 11,
"reply_count": 156,
"retweet_count": 78,
"favorite_count": 977,
"lang": "en",
"entities": {
"user_mentions": [
{
"id_str": "1311506622821400581",
"name": "Tesla Hype",
"screen_name": "TeslaHype",
"indices": [
0,
10
]
}
],
"urls": [],
"hashtags": [],
"symbols": []
},
"views_count": 32377,
"bookmark_count": 19
},
// ...
]
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested user does not exist
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
### Data API: Get Tweet
Source: [Get Tweet - API Reference](https://docs.socialdata.tools/reference/get-tweet/)
Endpoint: GET https://api.socialdata.tools/twitter/tweets/{id}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | integer | required | The numerical id of the target tweet
Example: `1729591119699124560` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/tweets/1729591119699124560" \
-H "Authorization: Bearer API_KEY" \
-H "Accept: application/json"
```
```javascript
const tweetId = '1729591119699124560';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/tweets/${tweetId}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
tweet_id = '1729591119699124560'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/tweets/{tweet_id}'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$tweetId = '1729591119699124560';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/tweets/{$tweetId}";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"tweet_created_at": "2022-07-19T06:35:54+00:00",
"id": 1549281861687451648,
"id_str": "1549281861687451648",
"text": null,
"full_text": "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": "chirr.app",
"truncated": false,
"in_reply_to_status_id": null,
"in_reply_to_status_id_str": null,
"in_reply_to_user_id": null,
"in_reply_to_user_id_str": null,
"in_reply_to_screen_name": null,
"user": {
"id": 15118774,
"id_str": "15118774",
"name": "Jake Mor",
"screen_name": "jakemor",
"location": "New York, USA",
"url": "http://superwall.com",
"description": "CEO @Superwall — build & test paywalls without shipping updates. Past: Founder @FitnessAI_ (acquired). YC W20 & S21",
"protected": false,
"verified": true,
"followers_count": 5423,
"friends_count": 556,
"listed_count": 95,
"favourites_count": 1161,
"statuses_count": 1683,
"created_at": "2008-06-14T18:37:41+00:00",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/15118774/1636564314",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1167559170540875777/nRn7p8em_normal.jpg",
"can_dm": true
},
"quoted_status_id": null,
"quoted_status_id_str": null,
"is_quote_status": false,
"quoted_status": null,
"retweeted_status": null,
"quote_count": 73,
"reply_count": 105,
"retweet_count": 492,
"favorite_count": 9419,
"views_count": null,
"bookmark_count": 4614,
"lang": "en",
"entities": {
"user_mentions": [
{
"id_str": "1427520876325613571",
"name": "Superwall",
"screen_name": "Superwall",
"indices": [
109,
119
]
}
],
"urls": [],
"hashtags": [],
"symbols": []
},
"is_pinned": false
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested tweet does not exist
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Data API: Get Tweet Retweeters List
Source: [Get Tweet Retweeters List - API Reference](https://docs.socialdata.tools/reference/get-tweet-retweeters/)
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.
Endpoint: GET https://api.socialdata.tools/twitter/tweets/{tweet_id}/retweeted_by?cursor={cursor}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| tweet_id | integer | required | The numerical ID of the desired Tweet
Example: `1729591119699124560` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| cursor | string | optional | Cursor value obtained from next_cursor response property. Omit this value to retrieve the first page
Example: `HBbS87H7icrezjEAAA==` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/tweets/1625802236571033602/retweeted_by" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const tweetId = '1625802236571033602';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/tweets/${tweetId}/retweeted_by`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
tweetId = '1625802236571033602'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/tweets/{tweetId}/retweeted_by'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$tweetId = '1625802236571033602';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/tweets/{$tweetId}/retweeted_by";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"next_cursor": "HBbS87H7icrezjEAAA==",
"users": [
{
"id": 1547124452596523008,
"id_str": "1547124452596523008",
"name": "Gwendal Brossard",
"screen_name": "GwendalBrossard",
"location": "Building",
"url": "https://t.co/6o4TTYu7LQ",
"description": "I'm an indie maker building products 👨💻 @PaletteBrain─https://t.co/BEadk6UDlz ✨",
"protected": false,
"verified": false,
"followers_count": 3557,
"friends_count": 149,
"listed_count": 41,
"favourites_count": 12425,
"statuses_count": 6778,
"created_at": "2022-07-13T07:43:56.000000Z",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1547124452596523008/1672736091",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1572151372455313409/qq1yH56d_normal.jpg",
"can_dm": true
},
// ...
]
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested tweet does not exist
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Data API: Get Tweet Quotes
Source: [Get Tweet Quotes - API Reference](https://docs.socialdata.tools/reference/get-tweet-quotes/)
Returns an array of quotes for a given tweet_id.
Endpoint: GET https://api.socialdata.tools/twitter/tweets/{id}/quotes?cursor={cursor}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | integer | required | The numerical id of the target tweet
Example: `1890269299287441612` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| cursor | string | optional | Cursor value obtained from next_cursor response property. Used to retrieve additional pages for the same query
Example: `1890084840239985036` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/tweets/1890269299287441612/quotes" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const tweetId = '1890269299287441612';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/tweets/${tweetId}/quotes`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
tweet_id = '1890269299287441612'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/tweets/{tweet_id}/quotes'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$tweet_id = '1890269299287441612';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/tweets/{$tweet_id}/quotes";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"tweets": [
{
"tweet_created_at": "2025-02-14T12:00:53.000000Z",
"id": 1890370626847682665,
"id_str": "1890370626847682665",
"conversation_id_str": "1890370626847682665",
"text": null,
"full_text": "I was gonna ask",
"source": "Twitter for iPhone",
"truncated": false,
"in_reply_to_status_id": null,
"in_reply_to_status_id_str": null,
"in_reply_to_user_id": null,
"in_reply_to_user_id_str": null,
"in_reply_to_screen_name": null,
"user": {
"id": 1820570848983732224,
"id_str": "1820570848983732224",
"name": "who cares",
"screen_name": "MDehart28372",
"location": "",
"url": null,
"description": "No DM's. old guy Army vet. Back after being kicked off for saying things that everyone can say now…..let's see if it lasts.",
"protected": false,
"verified": false,
"followers_count": 562,
"friends_count": 424,
"listed_count": 0,
"favourites_count": 31106,
"statuses_count": 36117,
"created_at": "2024-08-05T21:22:07.000000Z",
"profile_banner_url": null,
"profile_image_url_https": "https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png",
"can_dm": false
},
"quoted_status_id": null,
"quoted_status_id_str": "1890269299287441612",
"is_quote_status": true,
"quoted_status": {
"tweet_created_at": "2025-02-14T05:18:15.000000Z",
"id": 1890269299287441612,
"id_str": "1890269299287441612",
"conversation_id_str": "1890269299287441612",
"text": null,
"full_text": "I am so entertained",
"source": "Twitter for iPhone",
"truncated": false,
"in_reply_to_status_id": null,
"in_reply_to_status_id_str": null,
"in_reply_to_user_id": null,
"in_reply_to_user_id_str": null,
"in_reply_to_screen_name": null,
"user": {
"id": 44196397,
"id_str": "44196397",
"name": "Elon Musk",
"screen_name": "elonmusk",
"location": "",
"url": null,
"description": "Volunteer Tech Support",
"protected": false,
"verified": true,
"followers_count": 217621416,
"friends_count": 1025,
"listed_count": 160003,
"favourites_count": 123356,
"statuses_count": 70462,
"created_at": "2009-06-02T20:12:29.000000Z",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/44196397/1726163678",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1874558173962481664/8HSTqIlD_normal.jpg",
"can_dm": false
},
"quoted_status_id": null,
"quoted_status_id_str": null,
"is_quote_status": false,
"quoted_status": null,
"retweeted_status": null,
"quote_count": 930,
"reply_count": 8982,
"retweet_count": 6446,
"favorite_count": 114742,
"views_count": 18854541,
"bookmark_count": 1541,
"lang": "en",
"entities": {
"hashtags": [],
"symbols": [],
"timestamps": [],
"urls": [],
"user_mentions": []
},
"is_pinned": false
},
"retweeted_status": null,
"quote_count": 0,
"reply_count": 0,
"retweet_count": 0,
"favorite_count": 0,
"views_count": null,
"bookmark_count": 0,
"lang": "en",
"entities": {
"hashtags": [],
"symbols": [],
"timestamps": [],
"urls": [],
"user_mentions": []
},
"is_pinned": false
},
// ...
],
"next_cursor": "1890367029405696119"
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested tweet does not exist
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Data API: Get Tweet Comments
Source: [Get Tweet Comments - API Reference](https://docs.socialdata.tools/reference/get-tweet-comments/)
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).
Endpoint: GET https://api.socialdata.tools/twitter/tweets/{id}/comments?cursor={cursor}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | integer | required | The numerical id of the target tweet
Example: `1890269299287441612` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| cursor | string | optional | Cursor value obtained from next_cursor response property. Used to retrieve additional pages for the same query
Example: `1890084840239985036` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/tweets/1890269299287441612/comments" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const tweetId = '1890269299287441612';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/tweets/${tweetId}/comments`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));// JavaScript example
```
```python
import requests
tweet_id = '1890269299287441612'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/tweets/{tweet_id}/comments'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$tweet_id = '1890269299287441612';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/tweets/{$tweet_id}/comments";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"tweets": [
{
"tweet_created_at": "2025-02-14T12:01:25.000000Z",
"id": 1890370761136668854,
"id_str": "1890370761136668854",
"conversation_id_str": "1890269299287441612",
"text": null,
"full_text": "@elonmusk We can't thank you enough.",
"source": "Twitter Web App",
"truncated": false,
"in_reply_to_status_id": 1890269299287441612,
"in_reply_to_status_id_str": "1890269299287441612",
"in_reply_to_user_id": 44196397,
"in_reply_to_user_id_str": "44196397",
"in_reply_to_screen_name": "elonmusk",
"user": {
"id": 1366385465096630276,
"id_str": "1366385465096630276",
"name": "MYPOTUSTRUMP",
"screen_name": "11Pythagorean",
"location": "",
"url": null,
"description": "Shorten the refractory period of your emotional reactions-go confidently in the direction of your dreams—live the life you've imagined! Catholic #IDONOTCONSENT",
"protected": false,
"verified": false,
"followers_count": 2400,
"friends_count": 1460,
"listed_count": 3,
"favourites_count": 243414,
"statuses_count": 211500,
"created_at": "2021-03-01T13:51:11.000000Z",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1366385465096630276/1681663176",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1854480101385125894/uYkO23Fn_normal.jpg",
"can_dm": true
},
"quoted_status_id": null,
"quoted_status_id_str": null,
"is_quote_status": false,
"quoted_status": null,
"retweeted_status": null,
"quote_count": 0,
"reply_count": 0,
"retweet_count": 0,
"favorite_count": 0,
"views_count": 1,
"bookmark_count": 0,
"lang": "en",
"entities": {
"hashtags": [],
"symbols": [],
"timestamps": [],
"urls": [],
"user_mentions": [
{
"id_str": "44196397",
"name": "Elon Musk",
"screen_name": "elonmusk",
"indices": [
0,
9
]
}
]
},
"is_pinned": false
},
// ...
],
"next_cursor": "1890370499957461419"
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested tweet does not exist
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Data API: Get Tweets in a Twitter Thread
Source: [Get Tweets in a Twitter Thread - API Reference](https://docs.socialdata.tools/reference/get-tweet-thread/)
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)
Endpoint: GET https://api.socialdata.tools/twitter/thread/{thread_id}?cursor={cursor}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| thread_id | integer | required | The numerical ID of the desired thread
Example: `1729591119699124560` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| cursor | string | optional | Cursor value obtained from next_cursor response property
Example: `PAAAAPAtPBwcFoCAsrHQ6pOAKxUC...` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/thread/1549281861687451648" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const threadId = '1549281861687451648';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/thread/${threadId}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
threadId = '1549281861687451648'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/thread/{threadId}'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$threadId = '1549281861687451648';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/thread/{$threadId}";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"tweets": [
{
"tweet_created_at": "2022-07-19T06:35:54+00:00",
"id": 1549281861687451648,
"id_str": "1549281861687451648",
"text": null,
"full_text": "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": "chirr.app",
"truncated": false,
"in_reply_to_status_id": null,
"in_reply_to_status_id_str": null,
"in_reply_to_user_id": null,
"in_reply_to_user_id_str": null,
"in_reply_to_screen_name": null,
"user": {
"id": 15118774,
"id_str": "15118774",
"name": "Jake Mor",
"screen_name": "jakemor",
"location": "New York, USA",
"url": "http://superwall.com",
"description": "CEO @Superwall — build & test paywalls without shipping updates. Past: Founder @FitnessAI_ (acquired). YC W20 & S21",
"protected": false,
"verified": true,
"followers_count": 5423,
"friends_count": 556,
"listed_count": 95,
"favourites_count": 1161,
"statuses_count": 1683,
"created_at": "2008-06-14T18:37:41+00:00",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/15118774/1636564314",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1167559170540875777/nRn7p8em_normal.jpg",
"can_dm": true
},
"quoted_status_id": null,
"quoted_status_id_str": null,
"is_quote_status": false,
"quoted_status": null,
"retweeted_status": null,
"quote_count": 73,
"reply_count": 105,
"retweet_count": 492,
"favorite_count": 9419,
"views_count": null,
"bookmark_count": 4614,
"lang": "en",
"entities": {
"user_mentions": [
{
"id_str": "1427520876325613571",
"name": "Superwall",
"screen_name": "Superwall",
"indices": [
109,
119
]
}
],
"urls": [],
"hashtags": [],
"symbols": []
},
"is_pinned": false
},
// ...
],
"next_cursor": "PAAAAPAtPBwcFoCAsrHQ6pOAKxUCAAAYJmNvbnZlcnNhdGlvbnRocmVhZC0xNTQ5MjgxODYyNDYzNTA0Mzg0IgAA"
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested tweet does not exist
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Data API: Get Twitter Article
Source: [Get Twitter Article - API Reference](https://docs.socialdata.tools/reference/get-tweet-article/)
Returns tweet with an article attached to it. Output contains the same properties as tweet details endpoint, article content is returned within "article" attribute of the response.
Endpoint: GET https://api.socialdata.tools/twitter/article/{article_id}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| article_id | integer | required | The numerical ID of the desired article tweet.
Example: `1799137410284134858` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/article/1799137410284134858" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const articleId = '1799137410284134858';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/article/${articleId}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
articleId = '1799137410284134858'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/article/{articleId}'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$articleId = '1729591119699124560';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/article/{$tweetId}";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
// Example response would go here
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested tweet does not exist
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
When using languages where the article_id value exceeds the default Integer type limit (e.g., JavaScript), you should store article_id as a String. Use the id_str property returned by the API for these values.
### Data API: Get Twitter Space Details
Source: [Get Twitter Space Details - API Reference](https://docs.socialdata.tools/reference/get-space-details/)
Endpoint: GET https://api.socialdata.tools/twitter/space/{space_id}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| space_id | string | required | The ID of the desired Twitter Space.
Example: `1jMJgLdenVjxL` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/space/1jMJgLdenVjxL" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const id = '1jMJgLdenVjxL';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/space/${id}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
id = '1jMJgLdenVjxL'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/space/{id}'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$id = '1jMJgLdenVjxL';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/space/{$id}";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"state": "Ended",
"title": "The Algorithm goes open source",
"media_key": "28_1641872499875930112",
"created_at": 1680287883093,
"scheduled_start": 1680289200000,
"started_at": 1680289206898,
"ended_at": "1680293477270",
"updated_at": 1680293485413,
"disallow_join": false,
"narrow_cast_space_type": 0,
"is_employee_only": false,
"is_locked": false,
"is_space_available_for_replay": true,
"is_space_available_for_clipping": false,
"conversation_controls": 0,
"total_replay_watched": 1291373,
"total_live_listeners": 435271,
"id": "1jMJgLdenVjxL",
"creator": {
"id": "6844292",
"affiliates_highlighted_label": {
"label": {
"url": {
"url": "https://twitter.com/X",
"urlType": "DeepLink"
},
"badge": {
"url": "https://pbs.twimg.com/profile_images/1683899100922511378/5lY42eHs_bigger.jpg"
},
"description": "X",
"userLabelType": "BusinessLabel",
"userLabelDisplayType": "Badge"
}
},
"has_graduated_access": true,
"is_blue_verified": true,
"profile_image_shape": "Square",
"legacy": {
"can_dm": false,
"can_media_tag": true,
"created_at": "Sat Jun 16 00:14:36 +0000 2007",
"default_profile": false,
"default_profile_image": false,
"description": "Updates from our Product and Infrastructure teams.",
"entities": {
"description": {
"urls": []
}
},
"fast_followers_count": 0,
"favourites_count": 267,
"followers_count": 1324928,
"friends_count": 12,
"has_custom_timelines": true,
"is_translator": false,
"listed_count": 4701,
"location": "San Francisco",
"media_count": 63,
"name": "Engineering",
"normal_followers_count": 1324928,
"pinned_tweet_ids_str": [],
"possibly_sensitive": false,
"profile_banner_url": "https://pbs.twimg.com/profile_banners/6844292/1690213191",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1683502255574593536/anU7i4uA_normal.jpg",
"profile_interstitial_type": "",
"screen_name": "XEng",
"statuses_count": 905,
"translator_type": "regular",
"verified": false,
"verified_type": "Business",
"want_retweets": false,
"withheld_in_countries": []
}
}
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - Twitter space not found
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Data API: Get Community Members
Source: [Get Community Members - API Reference](https://docs.socialdata.tools/reference/get-community-members/)
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.
Endpoint: GET https://api.socialdata.tools/twitter/community/{community_id}/members?cursor={cursor}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| community_id | integer | required | Target community ID
Example: `1493446837214187523` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| cursor | string | optional | Cursor value obtained from next_cursor response property. Used to retrieve additional pages for the same query
Example: `DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0d...` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/community/1493446837214187523/members" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const communityId = '1493446837214187523';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/community/${communityId}/members`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
communityId = '1493446837214187523'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/community/{communityId}/members'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$communityId = '1493446837214187523';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/community/{$communityId}/members";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"next_cursor": "CycRAAAAAAwABAwKmwzBVQo+vQ0OGGp8lQABCm07AAABkNDNH5sADJorCj69f//////////KbTt//////////wAIP8AAAAADAAAA",
"users": [
{
"id": 3119483308,
"id_str": "3119483308",
"screen_name": "onofregasent",
"name": "Onofre",
"protected": false,
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1726870714131640320/Hsxgtxw9_normal.jpg",
"community_role": "Member"
},
{
"id": 338944755,
"id_str": "338944755",
"screen_name": "bohdanbasov",
"name": "Bohdan Basov",
"protected": false,
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1803862687895388160/2h7gpQ5U_normal.jpg",
"community_role": "Moderator"
},
// ...
]
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested community does not exist
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Data API: Get Community Tweets
Source: [Get Community Tweets - API Reference](https://docs.socialdata.tools/reference/get-community-tweets/)
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.
Endpoint: GET https://api.socialdata.tools/twitter/community/{community_id}/tweets?cursor={cursor}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| community_id | integer | required | Target community ID
Example: `1493446837214187523` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| cursor | string | optional | Cursor value obtained from next_cursor response property. Used to retrieve additional pages for the same query
Example: `DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0d...` |
| type | enum | optional | Search type (Latest for recent tweets or Top for popular tweets). Default - Latest
Example: `Top` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/community/1493446837214187523/tweets?type=Latest" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const communityId = '1493446837214187523';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/community/${communityId}/tweets?type=Latest`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
communityId = '1493446837214187523'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/community/{communityId}/tweets?type=Latest'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$communityId = '1493446837214187523';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/community/{$communityId}/tweets?type=Latest";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"next_cursor": "DAACCgACGC12FhmAJxAKAAMYLXYWGX_Y8AgABAAAAAILAAUAAADoRW1QQzZ3QUFBZlEvZ0dKTjB2R3AvQUFBQUJNWUxTNkQyQmFoUXhndFRReS9Ga0NOR0MwZG9yS1hzU2NZTFFwYm0xY1I0aGd0YmhZc1drQ3FHQzBjUXNSV1lSZ1lMVml5V3BxQU9CZ3RMbUhUV2tDb0dDMVFuVW1YMEFzWUxKYURhOVpob3hndFZtaklGakNNR0MxWGdlT1dZSE1ZTFRYNFNwZUEraGd0Y2h2bEYxRkxHQzFNMi83V1VGc1lMTTZwemhZQWt4Z3RWMkJKbDNGN0dDMWFGTXBYUUY4WUxUUERuRlp3UVE9PQgABgAAAAAIAAcAAAAADAAICgABGCyWg2vWYaMAAAA",
"tweets": [
{
"tweet_created_at": "2023-12-13T05:39:09.000000Z",
"id_str": "1734810168053956719",
"text": null,
"full_text": "@TeslaHype Pace of Progress",
"source": "Twitter for iPhone",
"truncated": false,
"in_reply_to_status_id_str": "1734777084268920960",
"in_reply_to_user_id_str": "1311506622821400581",
"in_reply_to_screen_name": "TeslaHype",
"user": {
"id_str": "44196397",
"name": "Elon Musk",
"screen_name": "elonmusk",
"location": "𝕏",
"url": null,
"description": "",
"protected": false,
"verified": false,
"followers_count": 166213349,
"friends_count": 506,
"listed_count": 149586,
"favourites_count": 37958,
"statuses_count": 34934,
"created_at": "2009-06-02T20:12:29.000000Z",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/44196397/1690621312",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1683325380441128960/yRsRRjGO_normal.jpg",
"can_dm": false
},
"quoted_status_id_str": null,
"is_quote_status": false,
"quoted_status": null,
"retweeted_status": null,
"quote_count": 11,
"reply_count": 156,
"retweet_count": 78,
"favorite_count": 977,
"lang": "en",
"entities": {
"user_mentions": [
{
"id_str": "1311506622821400581",
"name": "Tesla Hype",
"screen_name": "TeslaHype",
"indices": [
0,
10
]
}
],
"urls": [],
"hashtags": [],
"symbols": []
},
"views_count": 32377,
"bookmark_count": 19
},
// ... more tweets
]
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested community does not exist
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Data API: Get List Details
Source: [Get List Details - API Reference](https://docs.socialdata.tools/reference/get-list-details/)
Endpoint: GET https://api.socialdata.tools/twitter/lists/show?id={list_id}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| list_id | integer | required | The numeric ID of the desired list.
Example: `1625802236571033602` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/lists/show?id=1625802236571033602" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const listId = '1625802236571033602';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/lists/show?id=${listId}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
listId = '1625802236571033602'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/lists/show?id={listId}'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$listId = '1625802236571033602';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/lists/show?id={$listId}";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"created_at": 1676456433000,
"default_banner_media": {
"media_info": {
"original_img_url": "https://pbs.twimg.com/media/EXZ1_hkUYAA56JA.png",
"original_img_width": 1125,
"original_img_height": 375,
"salient_rect": {
"left": 562,
"top": 187,
"width": 1,
"height": 1
}
}
},
"default_banner_media_results": {
"result": {
"id": "QXBpTWVkaWE6DAABCgABEXZ1/hkUYAAKAAIQF4A+eBQgAAAA",
"media_key": "3_1258322880099540992",
"media_id": "1258322880099540992",
"media_info": {
"__typename": "ApiImage",
"original_img_height": 375,
"original_img_width": 1125,
"original_img_url": "https://pbs.twimg.com/media/EXZ1_hkUYAA56JA.png",
"salient_rect": {
"height": 1,
"left": 562,
"top": 187,
"width": 1
}
},
"__typename": "ApiMedia"
}
},
"description": "",
"facepile_urls": [
"https://pbs.twimg.com/profile_images/1685346185899294720/jYLsROeL_mini.jpg",
"https://pbs.twimg.com/profile_images/1706935000703315968/r6aQH0jg_mini.jpg",
"https://pbs.twimg.com/profile_images/1738612007451176960/cfTlBeMZ_mini.jpg"
],
"followers_context": "446 followers including @heyalexfriedman",
"following": false,
"id": "TGlzdDoxNjI1ODAyMjM2NTcxMDMzNjAy",
"id_str": "1625802236571033602",
"is_member": false,
"member_count": 50,
"members_context": "50 members",
"mode": "Public",
"muting": false,
"name": "Soloprenuers",
"pinning": false,
"subscriber_count": 446,
"user_results": {
"result": {
"__typename": "User",
"id": "VXNlcjoxNDY4MTkyMzY2NDU2NTQxMTg5",
"rest_id": "1468192366456541189",
"affiliates_highlighted_label": [],
"has_graduated_access": true,
"is_blue_verified": false,
"profile_image_shape": "Circle",
"legacy": {
"can_dm": true,
"can_media_tag": true,
"created_at": "Tue Dec 07 12:15:37 +0000 2021",
"default_profile": true,
"default_profile_image": false,
"description": "I help people learn JavaScript and address any doubts they may have along the way.",
"entities": {
"description": {
"urls": []
},
"url": {
"urls": [
{
"display_url": "tahajiru.com",
"expanded_url": "http://tahajiru.com",
"url": "https://t.co/iFLD4bkkj3",
"indices": [
0,
23
]
}
]
}
},
"fast_followers_count": 0,
"favourites_count": 5935,
"followers_count": 103,
"friends_count": 378,
"has_custom_timelines": true,
"is_translator": false,
"listed_count": 1,
"location": "India",
"media_count": 103,
"name": "Taha Jiruwala",
"normal_followers_count": 103,
"pinned_tweet_ids_str": [
"1666067236715659268"
],
"possibly_sensitive": false,
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1468192366456541189/1692881657",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1469317962288943106/aCRWoyOY_normal.jpg",
"profile_interstitial_type": "",
"screen_name": "tahajiru",
"statuses_count": 3264,
"translator_type": "none",
"url": "https://t.co/iFLD4bkkj3",
"verified": false,
"want_retweets": false,
"withheld_in_countries": []
}
}
}
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested list not found
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Data API: Get List Members
Source: [Get List Members - API Reference](https://docs.socialdata.tools/reference/get-list-members/)
Endpoint: GET https://api.socialdata.tools/twitter/lists/members?id={user_id}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| list_id | integer | required | The numeric ID of the desired list.
Example: `1625802236571033602` |
| cursor | string | optional | Cursor value obtained from next_cursor response property
Example: `4611686018541662731|1741085517660815316` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/lists/members?id=1625802236571033602" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const listId = '1625802236571033602';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/lists/members?id=${listId}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
listId = '1625802236571033602'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/lists/members?id={listId}'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$listId = '1625802236571033602';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/lists/members?id={$listId}";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"next_cursor": "4611686018541662731|1741080922217775060",
"users": [
{
"id": 1547124452596523008,
"id_str": "1547124452596523008",
"name": "Gwendal Brossard",
"screen_name": "GwendalBrossard",
"location": "Building",
"url": "https://t.co/6o4TTYu7LQ",
"description": "I'm an indie maker building products 👨💻 @PaletteBrain─https://t.co/BEadk6UDlz ✨",
"protected": false,
"verified": false,
"followers_count": 3557,
"friends_count": 149,
"listed_count": 41,
"favourites_count": 12425,
"statuses_count": 6778,
"created_at": "2022-07-13T07:43:56.000000Z",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/1547124452596523008/1672736091",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1572151372455313409/qq1yH56d_normal.jpg",
"can_dm": true
},
// ...
]
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested list not found
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Data API: Get List Tweets
Source: [Get List Tweets - API Reference](https://docs.socialdata.tools/reference/get-list-tweets/)
Endpoint: GET https://api.socialdata.tools/twitter/list/{list_id}/tweets?cursor={cursor}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| list_id | integer | required | The numeric ID of the desired list.
Example: `1625802236571033602` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| cursor | string | optional | Cursor value obtained from next_cursor response property. Used to retrieve additional pages for the same query
Example: `1890084840239985036` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/list/1625802236571033602/tweets" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const listId = '1625802236571033602';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/list/${listId}/tweets`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
list_id = '1625802236571033602'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/list/{list_id}/tweets'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$list_id = '1625802236571033602';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/list/{$list_id}/tweets";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"next_cursor": "1890347538525409734",
"tweets": [
{
"tweet_created_at": "2023-12-13T05:39:09.000000Z",
"id_str": "1734810168053956719",
"text": null,
"full_text": "@TeslaHype Pace of Progress",
"source": "Twitter for iPhone",
"truncated": false,
"in_reply_to_status_id_str": "1734777084268920960",
"in_reply_to_user_id_str": "1311506622821400581",
"in_reply_to_screen_name": "TeslaHype",
"user": {
"id_str": "44196397",
"name": "Elon Musk",
"screen_name": "elonmusk",
"location": "𝕏",
"url": null,
"description": "",
"protected": false,
"verified": false,
"followers_count": 166213349,
"friends_count": 506,
"listed_count": 149586,
"favourites_count": 37958,
"statuses_count": 34934,
"created_at": "2009-06-02T20:12:29.000000Z",
"profile_banner_url": "https://pbs.twimg.com/profile_banners/44196397/1690621312",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/1683325380441128960/yRsRRjGO_normal.jpg",
"can_dm": false
},
"quoted_status_id_str": null,
"is_quote_status": false,
"quoted_status": null,
"retweeted_status": null,
"quote_count": 11,
"reply_count": 156,
"retweet_count": 78,
"favorite_count": 977,
"lang": "en",
"entities": {
"user_mentions": [
{
"id_str": "1311506622821400581",
"name": "Tesla Hype",
"screen_name": "TeslaHype",
"indices": [
0,
10
]
}
],
"urls": [],
"hashtags": [],
"symbols": []
},
"views_count": 32377,
"bookmark_count": 19
},
// ... more tweets
]
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested list not found
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
## Monitoring API
### Monitoring API: Twitter Account Monitoring API Introduction
Source: [Twitter Account Monitoring API - Introduction](https://docs.socialdata.tools/monitoring/introduction/)
SocialData Monitoring API provides a convenient way to monitor actions by target users and receive notifications.
Four types of monitors are currently supported:
- User tweets monitor - triggered when a user posts a new tweet or makes a new retweet
- User following monitor - triggered when a user follows a new account
- User profile monitor - triggered when a user makes a change to their Twitter profile information (e.g. bio, location or a website)
- Pump.Fun monitor - triggered when a new link to pump.fun coin page is posted by any user with at least 1000 followers (only detects non shadow-banned users, i.e. visible in Twitter search)
Once a monitor detects the new tweet or followed user - it will trigger a webhook call to your backend with complete tweet & user data
#### Getting Started
- Obtain your SocialData API key
- Set the webhook URL where you will receive updates:
- Use POST /user/webhook endpoint to set a single global webhook URL that will receive events from all current and future monitors
- Or set webhook_url property when creating a new monitor to assign an individual webhook URL to each of your monitors
- Create your first monitor
Tip: We recommend setting a single global webhook URL instead of individual URLs for each monitor. Each webhook payload contains sufficient information to determine which monitor triggered the event.
### Monitoring API: Pricing
Source: [Pricing - Twitter Monitoring API](https://docs.socialdata.tools/monitoring/pricing/)
Unlike our Data API, the Monitoring API operates on a flat-rate, per-hour billing system. This means:
- You are charged a consistent hourly rate, regardless of the volume of tweets or user profiles received from the monitor.
- The first hourly charge is deducted when a monitor is created, subsequent charges are deducted at the beginning of every hour for every active monitor.
#### Price by Monitor Type
| Monitor Type | Price per Hour | Approximate Monthly Cost |
|--------------|----------------|--------------------------|
| User Tweets Monitor | $0.0042 | ~$3 |
| User Following Monitor | $0.0042 | ~$3 |
| User Profile Monitor | $0.0042 | ~$3 |
| Pump.Fun Monitor | $0.0645 | ~$50 |
All prices listed are preliminary and subject to change upon completion of beta testing.
### Monitoring API: Processing Webhooks
Source: [Processing Webhooks - API Reference](https://docs.socialdata.tools/monitoring/processing-webhooks/)
When a monitor detects an update (e.g., a new tweet from the target user), the API makes a POST request to your webhook URL. Each webhook request contains a single tweet or user profile. If the API detects multiple updates simultaneously, it dispatches an individual webhook request for each event.
The API first checks for a monitor-specific webhook_url (set using one of our "Create monitor" endpoints). If monitor-specific url is not defined, it uses your global webhook URL.
Currently, the API does not retry failed requests. However, this behavior may change in the future. We recommend always returning HTTP Status 200 for successfully received webhook requests.
#### Payload Structure
Each request contains 3 properties:
1. `event`: Defines the type of event that triggered a webhook and will always be one of `new_tweet`, `new_following`, or `profile_update`.
2. `data`: Contains the actual data of the event and is consistent with our tweet details or user details endpoints depending on the type of monitor.
3. `meta`: Contains details of the monitor that triggered the event.
#### Example Payload
```json
{
"event": "new_tweet",
"data": {
// ... Tweet details ...
},
"meta": {
"monitor_id": "01hx1r99s0nsqq1ffdhmyyqbfr",
"monitor_type": "user_tweets",
"monitored_id_str": "44196397"
}
}
```
### Monitoring API: Set Global Webhook URL
Source: [Set Global Webhook URL - API Reference](https://docs.socialdata.tools/monitoring/set-global-webhook-url/)
Used to set webhook URL that will be used for all monitors that don't have a monitor-specific webhook_url set
Endpoint: POST https://api.socialdata.tools/user/webhook
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Body
| Name | Type | Required | Description |
|------|------|----------|-------------|
| url | string | required | New webhook URL that will be used for all monitors that don't have an individual webhook_url set
Example: `https://my-website.com/webhook` |
#### Code Examples
```bash
curl -X POST "https://api.socialdata.tools/user/webhook" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"url": "https://my-website.com/webhook"}'
```
```javascript
const API_KEY = 'YOUR_API_KEY';
const webhookUrl = 'https://my-website.com/webhook';
fetch('https://api.socialdata.tools/user/webhook', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
'Accept': 'application/json'
},
body: JSON.stringify({ url: webhookUrl })
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
API_KEY = 'YOUR_API_KEY'
webhook_url = 'https://my-website.com/webhook'
url = 'https://api.socialdata.tools/user/webhook'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
payload = {'url': webhook_url}
response = requests.post(url, json=payload, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$API_KEY = 'YOUR_API_KEY';
$webhook_url = 'https://my-website.com/webhook';
$url = "https://api.socialdata.tools/user/webhook";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode(['url' => $webhook_url]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Content-Type: application/json",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"status": "success",
"message": "Webhook URL updated"
}
```
#### Response Codes
- 200 OK - request succeeded
- 404 Not Found - requested tweet does not exist
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
### Monitoring API: Create New User Tweets Monitor
Source: [Create New User Tweets Monitor - API Reference](https://docs.socialdata.tools/monitoring/create-user-tweets-monitor/)
Creates a new monitor to receive alerts when the target Twitter 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.
Endpoint: POST https://api.socialdata.tools/monitors/user-tweets
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Body
| Name | Type | Required | Description |
|------|------|----------|-------------|
| user_id | integer | required* | User ID of the target user. Required if user_screen_name not provided
Example: `1493446837214187523` |
| user_screen_name | string | required* | Username of the target user without @. Required if user_id not provided
Example: `elonmusk` |
| webhook_url | string | optional | Monitor-specific webhook URL that will override your global webhook URL. Not required
Example: `https://my-website.com/webhook` |
*Either user_id or user_screen_name must be provided
#### Code Examples
```bash
curl -X POST "https://api.socialdata.tools/monitors/user-tweets" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"user_id": 1493446837214187523}'
```
```javascript
const API_KEY = 'YOUR_API_KEY';
const userId = 1493446837214187523;
fetch('https://api.socialdata.tools/monitors/user-tweets', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
'Accept': 'application/json'
},
body: JSON.stringify({ user_id: userId })
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
API_KEY = 'YOUR_API_KEY'
user_id = 1493446837214187523
url = 'https://api.socialdata.tools/monitors/user-tweets'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
payload = {'user_id': user_id}
response = requests.post(url, json=payload, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$API_KEY = 'YOUR_API_KEY';
$user_id = 1493446837214187523;
$url = "https://api.socialdata.tools/monitors/user-tweets";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode(['user_id' => $user_id]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Content-Type: application/json",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"status": "success",
"data": {
"id": "01jm2569nf8jnn50zd8302vnpr",
"created_at": "2025-02-14T11:58:33.000000Z",
"monitor_type": "user_tweets",
"webhook_url": null,
"parameters": {
"user_screen_name": "MarioNawfal",
"user_name": "Mario Nawfal",
"user_id_str": "1319287761048723458"
}
}
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
### Monitoring API: Create Twitter User Following Monitor
Source: [Create Twitter User Following Monitor - API Reference](https://docs.socialdata.tools/monitoring/create-user-following-monitor/)
Creates a new monitor to receive alerts when the target Twitter user follows someone.
Endpoint: POST https://api.socialdata.tools/monitors/user-following
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Body
| Name | Type | Required | Description |
|------|------|----------|-------------|
| user_id | integer | required* | User ID of the target user. Required if user_screen_name not provided
Example: `1493446837214187523` |
| user_screen_name | string | required* | Username of the target user without @. Required if user_id not provided
Example: `elonmusk` |
| webhook_url | string | optional | Monitor-specific webhook URL that will override your global webhook URL. Not required
Example: `https://my-website.com/webhook` |
*Either user_id or user_screen_name must be provided
#### Code Examples
```bash
curl -X POST "https://api.socialdata.tools/monitors/user-following" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"user_id": 1493446837214187523}'
```
```javascript
const API_KEY = 'YOUR_API_KEY';
const userId = 1493446837214187523;
fetch('https://api.socialdata.tools/monitors/user-following', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
'Accept': 'application/json'
},
body: JSON.stringify({ user_id: userId })
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
API_KEY = 'YOUR_API_KEY'
user_id = 1493446837214187523
url = 'https://api.socialdata.tools/monitors/user-following'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
payload = {'user_id': user_id}
response = requests.post(url, json=payload, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$API_KEY = 'YOUR_API_KEY';
$user_id = 1493446837214187523;
$url = "https://api.socialdata.tools/monitors/user-following";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode(['user_id' => $user_id]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Content-Type: application/json",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"status": "success",
"data": {
"id": "01jm2569nf8jnn50zd8302vnpr",
"created_at": "2025-02-14T11:58:33.000000Z",
"monitor_type": "user_following",
"webhook_url": null,
"parameters": {
"user_screen_name": "MarioNawfal",
"user_name": "Mario Nawfal",
"user_id_str": "1319287761048723458"
}
}
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
### Monitoring API: Create Twitter User Profile Monitor
Source: [Create Twitter User Profile Monitor - API Reference](https://docs.socialdata.tools/monitoring/create-user-profile-monitor/)
Creates a new monitor to receive alerts when the target Twitter user changes their profile (e.g. updates their bio or location).
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
Endpoint: GET https://api.socialdata.tools/monitors/user-profile
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| user_id | integer | required* | User ID of the target user. Required if user_screen_name not provided
Example: `1493446837214187523` |
| user_screen_name | string | required* | Username of the target user without @. Required if user_id not provided
Example: `elonmusk` |
| webhook_url | string | optional | Monitor-specific webhook URL that will override your global webhook URL. Not required
Example: `https://my-website.com/webhook` |
*Either user_id or user_screen_name must be provided
#### Code Examples
```bash
curl -X POST "https://api.socialdata.tools/monitors/user-profile" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"user_id": 1493446837214187523}'
```
```javascript
const API_KEY = 'YOUR_API_KEY';
const userId = 1493446837214187523;
fetch('https://api.socialdata.tools/monitors/user-profile', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
'Accept': 'application/json'
},
body: JSON.stringify({ user_id: userId })
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
API_KEY = 'YOUR_API_KEY'
user_id = 1493446837214187523
url = 'https://api.socialdata.tools/monitors/user-profile'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
payload = {'user_id': user_id}
response = requests.post(url, json=payload, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$API_KEY = 'YOUR_API_KEY';
$user_id = 1493446837214187523;
$url = "https://api.socialdata.tools/monitors/user-profile";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode(['user_id' => $user_id]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Content-Type: application/json",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"status": "success",
"data": {
"id": "01jm2569nf8jnn50zd8302vnpr",
"created_at": "2025-02-14T11:58:33.000000Z",
"monitor_type": "user_profile",
"webhook_url": null,
"parameters": {
"user_screen_name": "MarioNawfal",
"user_name": "Mario Nawfal",
"user_id_str": "1319287761048723458"
}
}
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
### Monitoring API: Create New Pump.Fun Tweets Monitor
Source: [Create New Pump.Fun Tweets Monitor - API Reference](https://docs.socialdata.tools/monitoring/create-pump-fun-monitor/)
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.
Endpoint: POST https://api.socialdata.tools/monitors/search-pump-fun
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Body
| Name | Type | Required | Description |
|------|------|----------|-------------|
| webhook_url | string | optional | Monitor-specific webhook URL that will override your global webhook URL. Not required
Example: `https://my-website.com/webhook` |
#### Code Examples
```bash
curl -X POST "https://api.socialdata.tools/monitors/search-pump-fun" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'
```
```javascript
const API_KEY = 'YOUR_API_KEY';
fetch('https://api.socialdata.tools/monitors/search-pump-fun', {
method: 'POST',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
API_KEY = 'YOUR_API_KEY'
url = 'https://api.socialdata.tools/monitors/search-pump-fun'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
response = requests.post(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/monitors/search-pump-fun";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Content-Type: application/json",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"status": "success",
"data": {
"id": "01jmsjfcer1yhqb2qxgr3812f6",
"created_at": "2025-02-23T14:13:14.000000Z",
"monitor_type": "search_pump_fun",
"webhook_url": null,
"parameters": []
}
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
### Monitoring API: Get Monitor Details
Source: [Get Monitor Details - API Reference](https://docs.socialdata.tools/monitoring/get-monitor-details/)
Returns monitor details
Endpoint: GET https://api.socialdata.tools/monitors/{monitor_id}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| monitor_id | string | required | Target monitor ID
Example: `01jeg76qa91b095gttamsbwa6q` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/monitors/01jeg76qa91b095gttamsbwa6q" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const monitorId = '01jeg76qa91b095gttamsbwa6q';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/monitors/${monitorId}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
monitor_id = '01jeg76qa91b095gttamsbwa6q'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/monitors/{monitor_id}'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$monitor_id = '01jeg76qa91b095gttamsbwa6q';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/monitors/{$monitor_id}";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"status": "success",
"data": {
"id": "01jkf3zgfwt8gnpgevxf9w6h58",
"created_at": "2025-02-07T02:31:47.000000Z",
"monitor_type": "user_following",
"webhook_url": null,
"parameters": {
"user_screen_name": "elonmusk",
"user_name": "Elon Musk",
"user_id_str": "44196397"
}
}
}
```
#### Response Codes
- 200 OK - request succeeded
- 404 Not Found - requested monitor does not exist
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
### Monitoring API: List Active Monitors
Source: [List Active Monitors - API Reference](https://docs.socialdata.tools/monitoring/list-active-monitors/)
Returns a list of monitors owned by the user
Endpoint: GET https://api.socialdata.tools/monitors?page={page}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Query Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| page | integer | optional | Page number. Endpoint returns up to 50 monitors per page
Example: `2` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/monitors" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const API_KEY = 'YOUR_API_KEY';
fetch('https://api.socialdata.tools/monitors', {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
API_KEY = 'YOUR_API_KEY'
url = 'https://api.socialdata.tools/monitors'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/monitors";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"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
}
}
```
#### Response Codes
- 200 OK - request succeeded
- 404 Not Found - requested tweet does not exist
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
### Monitoring API: Edit Monitor Webhook URL
Source: [Edit Monitor Webhook URL - API Reference](https://docs.socialdata.tools/monitoring/edit-monitor-webhook/)
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
Endpoint: PATCH https://api.socialdata.tools/monitors/{monitor_id}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| monitor_id | string | required | Target monitor ID
Example: `01jeg76qa91b095gttamsbwa6q` |
#### Body
| Name | Type | Required | Description |
|------|------|----------|-------------|
| webhook_url | string | required | New webhook URL that will be used for all monitors that don't have an individual webhook_url set. Pass an empty value to remove monitor-specific webhook
Example: `https://my-website.com/webhook` or `NULL` |
#### Code Examples
```bash
curl -X PATCH "https://api.socialdata.tools/monitors/01jeg76qa91b095gttamsbwa6q" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"webhook_url": "https://my-website.com/webhook"}'
```
```javascript
const monitorId = '01jeg76qa91b095gttamsbwa6q';
const API_KEY = 'YOUR_API_KEY';
const webhookUrl = 'https://my-website.com/webhook';
fetch(`https://api.socialdata.tools/monitors/${monitorId}`, {
method: 'PATCH',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Content-Type': 'application/json',
'Accept': 'application/json'
},
body: JSON.stringify({ webhook_url: webhookUrl })
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
monitor_id = '01jeg76qa91b095gttamsbwa6q'
API_KEY = 'YOUR_API_KEY'
webhook_url = 'https://my-website.com/webhook'
url = f'https://api.socialdata.tools/monitors/{monitor_id}'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Content-Type': 'application/json',
'Accept': 'application/json'
}
payload = {'webhook_url': webhook_url}
response = requests.patch(url, json=payload, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$monitor_id = '01jeg76qa91b095gttamsbwa6q';
$API_KEY = 'YOUR_API_KEY';
$webhook_url = 'https://my-website.com/webhook';
$url = "https://api.socialdata.tools/monitors/{$monitor_id}";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PATCH',
CURLOPT_POSTFIELDS => json_encode(['webhook_url' => $webhook_url]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Content-Type: application/json",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"status": "success",
"data": {
"id": "01jksy1wv06r3jgk8d0bzahhwg",
"created_at": "2025-02-11T07:19:53.000000Z",
"monitor_type": "user_profile",
"webhook_url": "https://my-website.com/webhook", // contains new webhook_url or null
"parameters": {
"user_screen_name": "MarioNawfal",
"user_name": "Mario Nawfal",
"user_id_str": "1319287761048723458"
}
}
}
```
#### Response Codes
- 200 OK - request succeeded
- 404 Not Found - requested monitor does not exist
### Monitoring API: Delete Monitor
Source: [Delete Monitor - API Reference](https://docs.socialdata.tools/monitoring/delete-monitor/)
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.
Endpoint: DELETE https://api.socialdata.tools/monitors/{monitor_id}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| monitor_id | string | required | Target monitor ID
Example: `01jeg76qa91b095gttamsbwa6q` |
#### Code Examples
```bash
curl -X DELETE "https://api.socialdata.tools/monitors/01jeg76qa91b095gttamsbwa6q" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const monitorId = '01jeg76qa91b095gttamsbwa6q';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/monitors/${monitorId}`, {
method: 'DELETE',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
monitor_id = '01jeg76qa91b095gttamsbwa6q'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/monitors/{monitor_id}'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.delete(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$monitor_id = '01jeg76qa91b095gttamsbwa6q';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/monitors/{$monitor_id}";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => "DELETE",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"status": "success"
}
```
#### Response Codes
- 200 OK - request succeeded
- 404 Not Found - requested monitor does not exist
## Social Actions API
### Social Actions API: Verify user is following another user on Twitter/X
Source: [Verify user is following another user on Twitter/X - Social Actions API](https://docs.socialdata.tools/social-actions/verify-user-following/)
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.
Endpoint: GET https://api.socialdata.tools/twitter/user/{source_user_id}/following/{target_user_id}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| source_user_id | integer | required | The numeric ID of the follower user
Example: `1729591119699124560` |
| target_user_id | integer | required | The numeric ID of the user being followed
Example: `1729591119699124560` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/user/1319287761048723458/following/44196397" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const followerId = '1319287761048723458';
const targetId = '44196397';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/user/${followerId}/following/${targetId}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
followerId = '1319287761048723458'
targetId = '44196397'
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/user/{followerId}/following/{targetId}'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$followerId = '1319287761048723458';
$targetId = '44196397';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/user/{$followerId}/following/{$targetId}";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"status": "success",
"source_user_id": "123123123...",
"target_user_id": "456456456...",
"is_following": true,
"followers_checked_count": null // Deprecated, always null
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested target user does not exist
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Social Actions API: Verify user retweeted a tweet
Source: [Verify user retweeted a tweet - Social Actions API](https://docs.socialdata.tools/social-actions/verify-user-retweeted/)
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.
Endpoint: GET https://api.socialdata.tools/twitter/tweets/{tweet_id}/retweeted_by/{user_id}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Path Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| tweet_id | integer | required | The numeric ID of the target tweet
Example: `1625802236571033602` |
| user_id | integer | required | The numeric ID of the user
Example: `1489552236571048124` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/tweets/456456456/retweeted_by/123123123" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const tweetId = '456456456';
const userId = '123123123';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/tweets/${tweetId}/retweeted_by/${userId}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
tweetId = '456456456';
userId = '123123123';
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/tweets/{tweetId}/retweeted_by/{userId}'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$tweetId = '456456456';
$userId = '123123123';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/tweets/{$tweetId}/retweeted_by/{$userId}";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"status": "success",
"source_user_id": "123123123...",
"target_tweet_id": "456456456...",
"is_retweeted": true,
"retweeters_checked_count": null // Deprecated, always null
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested tweet does not exist
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Caution
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.
### Social Actions API: Verify user commented on a tweet on Twitter/X
Source: [Verify user commented on a tweet on Twitter/X - Social Actions API](https://docs.socialdata.tools/social-actions/verify-user-commented/)
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.
Endpoint: GET https://api.socialdata.tools/twitter/tweets/{tweet_id}/commented_by/{user_id}
#### Headers
| Name | Type | Required | Description |
|------|------|----------|-------------|
| Authorization | string | required | Authorization Bearer header containing your SocialData API key
Example: `Bearer YOUR_API_KEY` |
#### Parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| tweet_id | integer | required | The numeric ID of the target tweet
Example: `1625802236571033602` |
| user_id | integer | required | The numeric ID of the user
Example: `1489552236571048124` |
#### Code Examples
```bash
curl "https://api.socialdata.tools/twitter/tweets/456456456/commented_by/123123123" \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Accept: application/json'
```
```javascript
const tweetId = '456456456';
const userId = '123123123';
const API_KEY = 'YOUR_API_KEY';
fetch(`https://api.socialdata.tools/twitter/tweets/${tweetId}/commented_by/${userId}`, {
method: 'GET',
headers: {
'Authorization': `Bearer ${API_KEY}`,
'Accept': 'application/json'
}
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));
```
```python
import requests
tweetId = '456456456';
userId = '123123123';
API_KEY = 'YOUR_API_KEY'
url = f'https://api.socialdata.tools/twitter/tweets/{tweetId}/commented_by/{userId}'
headers = {
'Authorization': f'Bearer {API_KEY}',
'Accept': 'application/json'
}
response = requests.get(url, headers=headers)
if response.status_code == 200:
data = response.json()
print(data)
else:
print(f"Error: {response.status_code}")
print(response.text)
```
```php
$tweetId = '456456456';
$userId = '123123123';
$API_KEY = 'YOUR_API_KEY';
$url = "https://api.socialdata.tools/twitter/tweets/{$tweetId}/commented_by/{$userId}";
$ch = curl_init();
curl_setopt_array($ch, [
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer $API_KEY",
"Accept: application/json"
]
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);
curl_close($ch);
```
#### Example Responses
```json
{
"status": "success",
"is_commented": true,
"comment_ids": [
"1111111...",
"2222222...",
]
}
```
#### Response Codes
- 200 OK - request succeeded
- 402 Payment Required - not enough credits to perform this request
- 404 Not Found - requested user does not exist
- 422 Unprocessable Content - validation failed (e.g. one of the required parameters was not provided)
- 500 Internal Error - API internal error, typically means that SocialData API failed to obtain the requested information and you should try again later
#### Approach
This endpoint performs a number of tests to detect the relevant comment with high accuracy and low latency:
1. SocialData will attempt to retrieve a user's Tweets and replies page and check if any of their recent replies were posted in response to the target tweet_id (i.e. where in_reply_to_status_id == tweet_id) - this requires that a user's profile privacy is set to public and not "protected"
2. If the previous test fails, SocialData will also retrieve Twitter search results for the following query conversation_id:TWEET_ID (i.e. any comments posted under the target tweet)
3. SocialData will cache all detected comments on each request and validate subsequent requests against cache to minimize the latency of this endpoint.
#### Known Limitations
While in general this endpoint provides highly accurate results, it may occasionally fail to detect any relevant comments, even if the user commented on the target tweet, in the following cases:
- A comment was posted a long time ago and it is not found in the first few pages of the user's tweets and replies page, or in their comment search results
- A comment was posted by a shadow-banned user (i.e. marked by Twitter as spam/bot account) and their comments don't show up in search
However, you are unlikely to experience any of these issues if the endpoint is called shortly after the user posted their comment.
Keep in mind that the endpoint will not detect any deleted comments - if a comment_id was detected earlier, it will be stored in cache even if the user deletes it, and will be returned in subsequent endpoint responses. If your app needs to detect if any of the relevant comments were deleted - use the tweet details endpoint to retrieve the comment. Any deleted comments will result in error 404 Not Found
#### Caution
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.
## Additional Resources
### Twitter Search Operators
Source: [Twitter Search Operators](https://docs.socialdata.tools/resources/twitter-search-operators/)
#### Users
- `from:user` — Sent by a particular `@username` e.g. `"dogs from:NASA"`
- `to:user` — Replying to a particular `@username`
- `@user` — Mentioning a particular `@username`. Combine with `-from:username` to get only mentions
- `list:715919216927322112` or `list:esa/astronauts` — Tweets from members of this public list. Use the list ID from the API or with urls like `twitter.com/i/lists/715919216927322112`. List slug is for old list urls like `twitter.com/esa/lists/astronauts`. Cannot be negated, so you can't search for "not on list".
- `filter:blue_verified` — From "verified" users that paid $8 for Twitter Blue
#### Tweet Type
- `filter:nativeretweets` — Only retweets created using the retweet button. Works well combined with `from:` to show only retweets. Only works within the last 7-10 days or so.
- `include:nativeretweets` — Native retweets are excluded by default. This shows them. In contrast to `filter:`, which shows only retweets, this includes retweets in addition to other tweets. Only works within the last 7-10 days or so.
- `filter:retweets` — Old style retweets ("RT") + quoted tweets.
- `filter:replies` — Tweet is a reply to another Tweet. good for finding conversations, or threads if you add or remove `to:user`
- `filter:self_threads` — Only self-replies. Tweets that are part of a thread, not replies in other conversations.
- `conversation_id:tweet_id` — Tweets that are part of a thread (direct replies and other replies)
- `filter:quote` — Contain Quote Tweets
- `quoted_tweet_id:tweet_id` — Search for quotes of a specific tweet
- `quoted_user_id:user_id` — Search for all quotes of a specific user, by numeric User ID
#### Date & Time
- `until:2021-12-31` — Before (NOT inclusive) a specified date. Combine with a "since" operator for dates between.
- `since:2021-12-31_23:59:59_UTC` — On or after (inclusive) a specified date and time in the specified timezone. 4 digit year, 2 digit month, 2 digit day separated by `-` dashes, an `_` underscore separating the 24 hour clock format hours:minutes:seconds and timezone abbreviation.
- `until:2021-12-31_23:59:59_UTC` — Before (NOT inclusive) a specified date and time in the specified timezone. Combine with a "since" operator for dates between.
- `since_time:1142974200` — On or after a specified unix timestamp in seconds. Combine with the "until" operator for dates between. Maybe easier to use than `since_id` below.
- `until_time:1142974215` — Before a specified unix timestamp in seconds. Combine with a "since" operator for dates between. Maybe easier to use than `max_id` below.
- `since_id:tweet_id` — After (NOT inclusive) a specified Tweet ID
- `max_id:tweet_id` — At or before (inclusive) a specified Tweet ID
- `within_time:2d` or `within_time:3h` or `within_time:5m` or `within_time:30s` — Search within the last number of days, hours, minutes, or seconds
#### Tweet Content
- `url:google.com` — urls are tokenized and matched, works very well for subdomains and domains, not so well for long urls, depends on url. Youtube ids work well. Works for both shortened and canonical urls, eg: `gu.com` shortener for `theguardian.com`. When searching for Domains with hyphens in it, you have to replace the hyphen by an underscore (like `url:t_mobile.com`) but underscores `_` are also tokenized out, and may not match
- `lang:en` — Search for tweets in specified language, not always accurate
### Geo
- `near:city` — Geotagged in this place. Also supports Phrases, eg: `near:"The Hague"`
- `within:radius` — Within specific radius of the "near" operator, to apply a limit. Can use km or mi. e.g. `fire near:san-francisco within:10km`
- `geocode:lat,long,radius` — E.g., to get tweets 10km around twitters hq, use `geocode:37.7764685,-122.4172004,10km`
- `place:96683cc9126741d1` — Search tweets by place object ID, e.g.: USA Place ID is `96683cc9126741d1`
#### Engagement Filters
- `filter:has_engagement` — Has some engagement (replies, likes, retweets). Can be negated to find tweets with no engagement. Note all of these are mutually exclusive with `filter:nativeretweets` or `include:nativeretweets`, as they apply to the retweet, not the original tweet, so they won't work as expected.
- `min_retweets:5` — A minimum number of Retweets. Counts seem to be approximate for larger (1000+) values.
- `min_faves:10` — A minimum number of Likes
- `min_replies:100` — A minimum number of replies
- `-min_retweets:500` — A maximum number of Retweets
- `-min_faves:500` — A maximum number of Likes
- `-min_replies:100` — A maximum number of replies
#### Media
- `filter:media` — All media types.
- `filter:twimg` — Native Twitter images (`pic.twitter.com` links)
- `filter:images` — All images.
- `filter:videos` — All video types, including native Twitter video and external sources such as Youtube.
- `filter:periscope` — Periscopes
- `filter:native_video` — All Twitter-owned video types (native video, vine, periscope)
- `filter:vine` — Vines (RIP)
- `filter:consumer_video` — Twitter native video only
- `filter:pro_video` — Twitter pro video (Amplify) only
- `filter:spaces` — Twitter Spaces only
- `filter:links` — Only containing some URL, includes media. use `-filter:media` for urls that aren't media
- `filter:mentions` — Containing any sort of `@mentions`
- `filter:news` — Containing link to a news story. Combine with a list operator to narrow the user set down further
- `filter:safe` — Excluding NSFW content. Excludes content that users have marked as "Potentially Sensitive". Doesn't always guarantee SFW results.
- `filter:hashtags` — Only Tweets with Hashtags.