Create Twitter User Profile Monitor - API Reference

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

GET https://api.socialdata.tools/monitors/user-profile

Headers

Authorization string required

Authorization Bearer header containing your SocialData API key

Example: Bearer YOUR_API_KEY

Path Parameters

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

200

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

402

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

404

{
    "status": "error",
    "message": "User not found"
}

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 any changes in the profile of your target user, the API will make a POST request to your webhook URL with the following payload:

json

{
    "event": "profile_update",
    "data": {
      "id": 44196397,
      "id_str": "44196397",
      "name": "Kekius Maximus",
      "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,
      "changes": {
        "name": {
            "old": "Elon Musk",
            "new": "Kekius Maximus"
        }
    },
    "meta": {
        "monitor_id": "01jkt060zcz108b78fke6hm1g4",
        "monitor_type": "user_profile",
        "monitored_id_str": "44196397",
        "monitored_username": "elonmusk"
    }
}

TypeScript

interface ProfileUpdateEvent {
  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;
    changes: {
      [key: string]: {
        old: string;
        new: string;
      };
    };
  };
  meta: {
    monitor_id: string;
    monitor_type: string;
    monitored_id_str: string;
    monitored_username: string;
  };
}