Create New Search Query Monitor - API Reference

Creates a new search query monitor. SocialData will run your monitor every refresh_frequency seconds, retrieve recent search results for query, and dispatch each new matching tweet as an individual webhook event.

Each execution reads the most recent page of results and pages back only as far as it needs to reach tweets it has already seen, up to a maximum of 3 pages. A monitor that keeps up with its query normally reads a single page per execution.

Delivery behaviour

The first execution delivers nothing. It records which tweets already match your query so that only genuinely new ones are reported afterwards. Tweets posted before you created the monitor are never delivered.
Each tweet is delivered once. A tweet that keeps matching your query on later executions is not re-sent.
Tweets that are already old when found are skipped. If a tweet surfaces in search long after it was posted, it is not delivered. The cutoff is twice your refresh_frequency, or 10 minutes, whichever is longer.
The monitor pauses if your balance runs out, and resumes when you top up.

Cost

Search monitors are billed $0.0002 per delivered tweet, and $0.0002 for each execution that delivers nothing — every execution runs a real Twitter search whether or not it matches. Your floor cost is therefore set by refresh_frequency: at the default 30 seconds, a monitor executes 2,880 times a day and costs at least ~$17/month even if it never matches anything. See Pricing before choosing a frequency.

POST https://api.socialdata.tools/monitors/search-query

Headers

Authorization string required

Authorization Bearer header containing your SocialData API key

Example: Bearer YOUR_API_KEY

Body

query string required

A UTF-8, URL-encoded search query of up to 512 characters, including any operators supported by Twitter's website search

Example: from:elonmusk doge

refresh_frequency integer optional

How often the monitor executes, in seconds (value between 1 and 3600). This is the main driver of what the monitor costs — see Pricing

Example: 300

webhook_url string optional

Monitor-specific webhook URL that will override your global webhook URL. Not required.

If you want to send events to Discord or Telegram, please read the following section

Example: https://my-website.com/webhook

Code Examples

curl -X POST "https://api.socialdata.tools/monitors/search-query" \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    -d '{"refresh_frequency": 30, "query": "from:elonmusk"}'

const API_KEY = 'YOUR_API_KEY_HERE';

fetch('https://api.socialdata.tools/monitors/search-query', {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
        'Accept': 'application/json'
    },
    body: JSON.stringify({
        refresh_frequency: 30,
        query: "from:elonmusk"
    })
})
.then(response => response.json())
.then(response => console.log(response))
.catch(err => console.error(err));

import requests

API_KEY = 'YOUR_API_KEY_HERE'

url = 'https://api.socialdata.tools/monitors/search-query'

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json',
    'Accept': 'application/json'
}

payload = {
    'refresh_frequency': 30,
    'query': 'from:elonmusk'
}

response = requests.post(url, headers=headers, json=payload)

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

$url = "https://api.socialdata.tools/monitors/search-query";

$ch = curl_init();

$payload = json_encode([
    'refresh_frequency' => 30,
    'query' => 'from:elonmusk'
]);

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"
    ],
    CURLOPT_POSTFIELDS => $payload
]);

$response = curl_exec($ch);
$data = json_decode($response, true);
print_r($data);

curl_close($ch)

Example Responses

{
    "status": "success",
    "data": {
        "id": "01jqty3m3dhg9xpsj373x12ck7",
        "created_at": "2025-04-02T09:42:51.000000Z",
        "monitor_type": "search_keyword",
        "status": "active",
        "webhook_url": "...",
        "parameters": {
            "query": "from:elonmusk"
        },
        "refresh_frequency": "30"
    }
}

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

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)

Webhook Payload Example

When a monitor detects a new tweet that matches the target search query, the API will make a POST request to your webhook URL with the following payload:

json
TypeScript

{
    "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": "search_keyword",
        "monitored_query": "from:elonmusk"
    }
}

interface NewTweetEvent {
  event: string;
  data: Tweet;
  meta: {
    monitor_id: string;
    monitor_type: string;
    // Search monitors report the query they matched. User monitors
    // report monitored_id_str and monitored_username instead.
    monitored_query: 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;
}

Receiving Events in Telegram or Discord

The SocialData Monitor event schema differs from what Discord or Telegram expect. If you would like to receive notifications in your Discord channel or Telegram bot, we provide pre-built webhook handlers hosted on Val Town, eliminating the need to develop your own custom application.

Simply copy the following webhook handler to your own Val Town account and configure your monitor’s webhook_url to direct events to your webhook handler: Tweet event webhook handler