Skip to content

Create New Search Query Monitor - API Reference

Creates a new search query monitor. SocialData will run your monitor every refresh_frequency seconds and retrieve recent search results for query search query.

The monitor will retrieve up to 5 pages of search results (typically ~100 most recent tweets) and dispatch each new tweet as an individual webhook event. The monitor also keeps track of last retrieved tweet and will stop execution when it reaches previously retrieved search results to minimize the cost.

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, including any operators supported by Twitter website search

Example: from:elonmusk doge

refresh_frequency integer required

Monitor update frequency in seconds (value between 1 and 3600)

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

Terminal window
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"}'

Example Responses

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

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 contains the target search query, 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": "search_keyword",
        "monitored_query": "from:elonmusk"
    }
}