Create New User Tweets Monitor - API Reference
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.
POST https://api.socialdata.tools/monitors/user-tweets
Headers
Authorization string required
Authorization Bearer header containing your SocialData API key
Example: Bearer YOUR_API_KEY
Body
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
Code Examples
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}'const API_KEY = 'YOUR_API_KEY_HERE';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));import requests
API_KEY = 'YOUR_API_KEY_HERE'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)$API_KEY = 'YOUR_API_KEY_HERE';$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
{ "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" } }}{ "status": "error", "message": "Insufficient balance"}{ "status": "error", "message": "Not found"}{ "status": "error", "message": "Failed to fetch data from Twitter"}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
Webhook Payload Example
When a monitor detects a new tweet posted by the target user, the API will make a POST request to your webhook URL with the following payload:
{ "event": "new_tweet", "data": { "tweet_created_at": "2025-02-12T02:43:10.000000Z", "id": 1889505498761703504, "id_str": "1889505498761703504", "conversation_id_str": "1889505498761703504", "text": null, "full_text": "Assange is right!", "source": "<a href=\"http:\/\/twitter.com\/download\/iphone\" rel=\"nofollow\">Twitter for iPhone<\/a>", "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": "", "protected": false, "verified": true, "followers_count": 217258406, "friends_count": 1013, "listed_count": 159662, "favourites_count": 122139, "statuses_count": 70054, "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": "1889494636323885155", "is_quote_status": true, "quoted_status": { "tweet_created_at": "2025-02-12T02:00:01.000000Z", "id": 1889494636323885155, "id_str": "1889494636323885155", "conversation_id_str": "1889494636323885155", "text": null, "full_text": "\ud83d\udea8ASSANGE ON USAID: \u2018CIVIL SOCIETY IS A FABLE\u2019\n\nAssange exposed how NGOs have been co-opted into political weapons, arguing that civil society is no longer independent but a \u201cbuyer\u2019s market\u201d for influence:\n\n\u201cThe last forty years have seen a huge proliferation of think tanks and political NGOs whose purpose, beneath all the verbiage, is to execute political agendas by proxy.\u201d\n\nHe singled out USAID, Freedom House, and \u2018civil society\u2019 events as vehicles for Western political interests masquerading as grassroots activism.\n\nSource: @WikiLeaks", "source": "<a href=\"http:\/\/twitter.com\" rel=\"nofollow\">Twitter Web Client<\/a>", "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": 1319287761048723458, "id_str": "1319287761048723458", "name": "Mario Nawfal", "screen_name": "MarioNawfal", "location": "", "url": "https:\/\/roundtable.live", "description": "Largest Show on X | Founder @ibcgroupio", "protected": false, "verified": true, "followers_count": 2030538, "friends_count": 44251, "listed_count": 8614, "favourites_count": 144210, "statuses_count": 109900, "created_at": "2020-10-22T14:42:25.000000Z", "profile_banner_url": "https:\/\/pbs.twimg.com\/profile_banners\/1319287761048723458\/1736691634", "profile_image_url_https": "https:\/\/pbs.twimg.com\/profile_images\/1670905743619268609\/pYItlWat_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": 16, "reply_count": 51, "retweet_count": 350, "favorite_count": 871, "views_count": 26067, "bookmark_count": 54, "lang": "en", "entities": { "user_mentions": [ { "id_str": "16589206", "name": "WikiLeaks", "screen_name": "WikiLeaks", "indices": [ 532, 542 ] } ], "urls": [], "hashtags": [], "symbols": [] }, "is_pinned": false }, "retweeted_status": null, "quote_count": 0, "reply_count": 7, "retweet_count": 0, "favorite_count": 1, "views_count": null, "bookmark_count": 2, "lang": "en", "entities": { "user_mentions": [], "urls": [], "hashtags": [], "symbols": [] }, "is_pinned": false }, "meta": { "monitor_id": "01jkt060zcz108b78fke6hm1g4", "monitor_type": "user_tweets", "monitored_id_str": "44196397", "monitored_username": "elonmusk" }}interface NewTweetEvent { event: string; data: Tweet; meta: { monitor_id: string; monitor_type: string; monitored_id_str: string; monitored_username: string; };}
interface Tweet { tweet_created_at: string; id: number; id_str: string; conversation_id_str: string | null; text: string | null; full_text: string; source: string; truncated: boolean; in_reply_to_status_id: number | null; in_reply_to_status_id_str: string | null; in_reply_to_user_id: number | null; in_reply_to_user_id_str: string | null; in_reply_to_screen_name: string | null; user: User; quoted_status_id: number | null; quoted_status_id_str: string | null; is_quote_status: boolean; quoted_status: Tweet | null; retweeted_status: Tweet | null; quote_count: number; reply_count: number; retweet_count: number; favorite_count: number; views_count: number | null; bookmark_count: number; lang: string; entities: any; is_pinned: boolean;}
interface User { id: number; id_str: string; name: string; screen_name: string; location: string; url: string | null; description: string; protected: boolean; verified: boolean; followers_count: number; friends_count: number; listed_count: number; favourites_count: number; statuses_count: number; created_at: string; profile_banner_url: string; profile_image_url_https: string; can_dm: boolean;}