Twitter Account Monitoring API - Introduction

SocialData Monitoring API watches Twitter on your behalf and pushes events to your server shortly after they happen. You create a monitor, we check for updates continuously, and every new event becomes a POST request to your webhook URL containing complete tweet or user data.

There is nothing to poll and nothing to schedule on your side.

Monitor types

User Tweets Monitor - triggered when a user posts a new tweet, reply, quote or retweet
User Following Monitor - triggered when a user follows a new account
User Profile Monitor - triggered when a user changes their Twitter profile information (e.g. name, bio, location, website or profile image)
Search Query Monitor - runs any custom search query at a frequency you define and delivers new matching tweets

User monitors are event-driven: we watch each account continuously and deliver every change we detect, typically within 30 seconds — see Delivery timing. Search monitors run on the schedule you choose. The two types are billed differently — see Pricing.

Delivery timing

We do not promise real-time delivery. A user monitor delivers an event up to 30 seconds after the change happens on X, and usually well under that. We are actively working to reduce this as the feature rolls out to more users.

Treat the delay as normal rather than exceptional: handle events whenever they arrive, and don’t build a flow that assumes a webhook lands the instant someone posts. If your use case depends on sub-second reaction, the Monitoring API is not the right tool today.

Search monitors are different — their timing is governed by the refresh_frequency you set, plus the same delivery delay.

Getting Started

Obtain your SocialData API key
Set up your webhook handler

Create a webhook endpoint on your own server to handle received webhook events
Or expose your local development environment through a public URL using Ngrok or Cloudflare Tunnel - Only recommended while testing, not for production-ready applications

Set the webhook URL where you will receive updates

Use POST /user/webhook endpoint to set a single default webhook URL that will receive events from all current and future monitors
Or set the webhook_url property when creating a new monitor to assign an individual webhook URL to each of your monitors

Create your first monitor

What to expect after creating a monitor

A monitor reports what happens next, not what already happened. Creating a monitor establishes a baseline from the current state of the account or search query. Tweets posted before you created the monitor are not delivered, and neither are profile values that were already set. This applies to every monitor type — if you need the existing data, fetch it once from the Data API when you create the monitor.

Each event is delivered on its own. If a monitor detects five new tweets at the same time, you receive five separate webhook requests rather than one batched payload.

Events are deduplicated. The same tweet is never delivered twice by the same monitor, even if it keeps appearing in search results or a timeline is re-checked.

Monitors pause when your balance runs out and resume automatically when you top up. See Pricing.

Reviewing delivered events

Every webhook we send is recorded. If your endpoint was down or you want to inspect exactly what we sent, use Monitor event history to list a monitor’s recent events and re-read their payloads and delivery status.

Receiving Events in Telegram or Discord

To simplify the process of receiving 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 fork one of these handlers and configure your monitor’s webhook_url to direct events to your Val Town application:

Val Town is a robust platform for creating, executing, and sharing lightweight JavaScript or TypeScript code snippets directly in your browser, offering a simple and efficient solution for rapid deployment without complex infrastructure.