Create Twitter User Following Monitor - API Reference

Creates a new monitor to receive alerts when the target Twitter user follows someone.

POST https://api.socialdata.tools/monitors/user-following

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

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_HERE';
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_HERE'
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_HERE';
$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

200

{
  "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"
    }
  }
}

402

{
    "status": "error",
    "message": "Insufficient balance"
}

500

{
    "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 user followed by the target user, the API will make a POST request to your webhook URL with the following payload:

json

{
  "event": "new_following",
  "data": {
    "id": 295218901,
    "id_str": "295218901",
    "name": "vitalik.eth",
    "screen_name": "VitalikButerin",
    "location": "Earth",
    "url": null,
    "description": "mi pinxe lo crino tcati",
    "protected": false,
    "verified": true,
    "followers_count": 5702740,
    "friends_count": 465,
    "listed_count": 37058,
    "favourites_count": 8856,
    "statuses_count": 20628,
    "created_at": "2011-05-08T16:03:03.000000Z",
    "profile_banner_url": "https://pbs.twimg.com/profile_banners/295218901/1638557376",
    "profile_image_url_https": "https://pbs.twimg.com/profile_images/1880759276169224192/rXpjZO0A_normal.jpg",
    "can_dm": false
  },
  "meta": {
    "monitor_id": "01jkt060zcz108b78fke6hm1g4",
    "monitor_type": "user_following",
    "monitored_id_str": "44196397",
    "monitored_username": "elonmusk"
  }
}

TypeScript

interface NewFollowingEvent {
  event: string;
  data: {
    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;
  };
  meta: {
    monitor_id: string;
    monitor_type: string;
    monitored_id_str: string;
    monitored_username: string;
  };
}