Monitoring Twitter (X) Tweets via API — A Developer's Guide
Monitoring a Twitter (X) account, a brand mention, or a keyword in close-to-real-time is one of the most common production uses of the X API. Marketing teams set up brand-mention alerts; trading desks watch for market-moving tweets; brand-safety platforms scan for crisis signals; analytics teams capture timeline data for downstream analysis. Each use case has a different latency requirement and a different cost profile, and the architectural choice you make at the start — polling versus streaming versus webhook — locks in those properties for the life of the system.
This guide walks through the three monitoring architectures with their trade-offs, gives a runnable Python example for the most common pattern (timeline polling with engagement re-fetch), and covers the cost economics that determine whether the official X API or a third-party API like TwitterAPI.io is the right fit for your scale. It assumes you know what an HTTP API is; everything else is in-context.
By the end, you'll have: a clear answer to which monitoring pattern fits your use case, a ~70-line Python reference implementation you can copy and adapt, and a concrete monthly-cost estimate for 1 / 10 / 100 / 1,000 accounts at the recommended cadence.
Three architectural patterns — pick the right one before you write code
There are three architecturally distinct ways to monitor Twitter (X) in production. Picking one is the single highest-leverage decision in a monitoring system; switching between them after you've shipped is significantly more work than picking right the first time.
1. Timeline polling. Periodically fetch a user's recent tweets or a search result, diff against your last-known state, write new items to storage. Simplest to operate; freshness limited by your poll interval. Most third-party APIs make this the cheapest path. Right answer for ~80% of monitoring use cases.
2. Filtered stream. Subscribe to a filter rule (e.g. from:elonmusk or "product launch") and receive matching tweets via a long-lived WebSocket. Sub-second freshness; requires you to operate a persistent worker (not serverless-friendly). On TwitterAPI.io: oapi/tweet_filter/add_rule + a wss:// connection. On official X API: the Filtered Stream endpoint, Pro tier and up.
3. Webhook callbacks. Same push pattern but stateless on your side — the API service hits your HTTPS endpoint with each matching tweet. Operationally easiest for serverless deploys (Vercel/Cloudflare Workers/Lambda); slightly higher per-event cost than the WebSocket stream. Pattern of choice when you don't want to run anything 24/7.
A simple decision rule: if you can tolerate 60-second latency, polling. If you need sub-5-second and don't want to run a persistent worker, webhooks. If you need sub-second for high-stakes alerting, filtered stream.
The Twitter (X) API surface you'll use — endpoints, auth, and the official-vs-third-party choice
For each monitoring pattern, there's a specific subset of the X API surface that gets used. Knowing the names up front saves time when you're debugging.
Timeline polling endpoints:
GET /twitter/user/info — resolve a handle to a user ID (TwitterAPI.io). Equivalent: GET /2/users/by/username/:username on official X API.
GET /twitter/user/last_tweets — most recent ~20 tweets for a user (TwitterAPI.io). Equivalent: GET /2/users/:id/tweets.
GET /twitter/tweet/advanced_search — keyword/operator search (TwitterAPI.io). Equivalent: GET /2/tweets/search/recent.
Filtered stream endpoints:
POST /oapi/tweet_filter/add_rule + wss://ws.twitterapi.io/twitter/tweet/stream (TwitterAPI.io).
POST /2/tweets/search/stream/rules + GET /2/tweets/search/stream (official X API; Pro tier).
Authentication. TwitterAPI.io uses a single X-API-Key HTTP header — no OAuth flow, no project approval. Official X API uses OAuth (4 keys + signed requests for User context, or a Bearer Token for App context). The 4-key OAuth signing is a real source of bugs when you're prototyping; the third-party single-header path is what most teams use to move fast and migrate later if needed.
Cost comparison at the per-call level (2026 docs.x.com):
The per-call gap is roughly 33× — TwitterAPI.io reads cost about 1/33 of the official X API rate. For high-volume monitoring (the use case this whole guide is about), that cost gap usually determines which path is economically viable at scale.
Runnable Python — a timeline-polling monitor with engagement re-fetch
Below is a working Python implementation of the recommended pattern (timeline polling with engagement re-fetch) targeting a single account. It polls every 60 seconds, dedupes against local state, appends new tweets to JSONL, and schedules engagement-velocity re-fetches at T+15m, T+1h, T+6h, T+24h. Total cost at this cadence: roughly $1/month per account on TwitterAPI.io.
Key implementation notes embedded in the script:
We resolve the handle once via user/info and cache the user_id locally — saves one call per poll across restarts.
We dedupe on tweet.id against a local file so restarts don't replay tweets.
Engagement velocity (likes/min in the first 15 minutes) is widely cited as a leading indicator of viral potential — often more diagnostic than the final engagement count alone, since the final count is reached well after the decision-relevant window. Capturing it at multiple time points lets you measure the velocity curve rather than relying on a single point estimate.
The script writes events with a kind field (new_tweet vs velocity_checkpoint) so downstream consumers can join them with a single GROUP BY.
**Replace HANDLE** = "elonmusk" with your target. For multi-account watch, run one process per account (cheap) or refactor into a single loop iterating a handle list (slightly more code, same behavior).
Drop-in alerting hook. The print("SPIKE: ...") line at the bottom of the engagement check is where you'd integrate Slack/PagerDuty/SES/whatever. The condition engagement > median * SPIKE_MULTIPLIER is the simplest spike detector that doesn't fire on baseline noise; tune SPIKE_MULTIPLIER per account.
Filtered stream — when polling isn't fast enough
Switch from polling to filtered stream when one of these conditions holds:
Latency requirement < 5 seconds (alerting products, trading bots)
You're watching keywords/operators rather than specific accounts, and the keyword volume is high enough that polling search every minute would miss tweets that get deleted in seconds
You need to capture tweets before deletions land (e.g. high-profile accounts that delete frequently)
The trade-off. Filtered stream requires you to run a persistent process that keeps the WebSocket open. That excludes serverless (Vercel/Lambda) and adds operational complexity (process supervisor, connection retry, monitoring the monitor). For real-time alerting it's worth it; for analytics archiving it usually isn't.
Rule design. On both TwitterAPI.io and the official X API, you POST a filter rule with operators like from:userid or "product launch" OR "new release" -is:retweet. The rule language is shared X API search-operator syntax; the same query that works on Search Tweets works on Filtered Stream. Limit yourself to 5-10 rules per process at first; complex rule sets get expensive to debug.
Reconnection. WebSocket disconnects happen. Build in an exponential-backoff reconnect, and after reconnect, query the stream for the last N minutes via Search Tweets to fill any gap. That gap-filling step is the difference between a streaming system that's almost always live and one you can actually deploy.
Webhooks — the stateless push pattern for serverless deploys
If you want push semantics but don't want to run a persistent worker, webhooks are the right answer. TwitterAPI.io's webhook pattern: register your HTTPS endpoint + a filter rule via oapi/tweet_filter/add_rule, and the API hits your endpoint with each matching tweet within a few seconds of publication.
Why webhooks fit serverless well. Each tweet is a single HTTP POST to your endpoint, your function handles it, returns 2xx, exits. No long-lived process. Vercel Functions, Cloudflare Workers, AWS Lambda — all native fit. You scale to zero between tweets and pay only when one fires.
Per-event cost. Slightly higher than WebSocket stream (the API service is doing the HTTP delivery work for you), but for low-volume filters (single brand mentions, single VIP account watches) the cost difference is negligible — and the operational savings of not running anything 24/7 usually dominate.
Webhook design rules.
Always return 2xx within ~10 seconds; do downstream work asynchronously (queue → worker). A slow webhook gets retried, which means duplicate processing.
Verify the webhook signature on every request. Otherwise an attacker can spoof tweets into your alerting stream.
De-dupe on tweet_id server-side — webhooks have at-least-once delivery semantics.
Cost economics at scale — when each path stops working
The monitoring path that's right for 1 account is rarely the same path that's right for 1,000 accounts. The per-call cost difference compounds.
Scenario: timeline polling at 60-second cadence per account.
At 100 accounts on the official X API, you're spending more than most teams' entire monitoring budget. At 1,000 accounts, the official path is closed unless you have a contract sizable enough to negotiate enterprise rates — and even then, the third-party path is typically much cheaper because there's no comparable enterprise-tier on the TwitterAPI.io side; the per-call rate stays flat.
A practical rule. If you're monitoring fewer than 10 accounts and need < $30/month total, either path works. If you're monitoring 50+ accounts or need < $100/month total, the third-party path is usually the only economically viable choice for monitoring at production scale. See [our X API cost breakdown for the underlying per-call math](/blog/x-api-cost-breakdown-2026) and [the 2026 official pricing docs](/blog/twitter-api-pricing) for the exact official-API rate card.
Operational notes — rate limits, deletion archives, alerting design
Three operational notes that matter once you're past the prototype stage:
Rate limits behave differently per path. Official X API has per-endpoint 15-minute caps (75-900 requests per 15 min depending on endpoint). TwitterAPI.io has no equivalent strict 15-minute window — you get spending-limit control instead. See [our JP rate-limit reference for the cap table](/blog/twitter-rate-limit-exceeded) for the exact official numbers.
Deletion archives. Tweets sometimes vanish within seconds of posting (especially on high-deletion-rate accounts). Timeline polling will miss those; only filtered stream captures them. If you need a deletion-aware archive, layer your timeline poll with periodic re-fetches of older tweet IDs and flag the ones that 404 — that's the only signal the public API surface gives.
Alerting design. The single biggest failure mode of monitoring systems is alert fatigue. Tune your spike thresholds per account/keyword (median × multiplier, not absolute counts), de-dupe identical alerts within a window, and route VIP signals (high-follower posters, high-engagement-velocity tweets) to a separate higher-urgency channel. The runnable Python in the section above is the simplest version of this; a production system layers a few more checks on top.
# pip install requests
import json
import time
import statistics
import pathlib
import requests
API_KEY = "YOUR_TWITTERAPI_IO_KEY"
BASE = "https://api.twitterapi.io"
HANDLE = "elonmusk" # change to whoever you're monitoring
POLL_INTERVAL = 60 # seconds
VELOCITY_CHECKPOINTS = [15, 60, 360, 1440] # minutes after first-seen
SPIKE_MULTIPLIER = 3.0 # tune per account
STATE_DIR = pathlib.Path(".state")
STATE_DIR.mkdir(exist_ok=True)
IDS = STATE_DIR / f"{HANDLE}_seen.json"
VEL = STATE_DIR / f"{HANDLE}_velocity.json"
OUT = STATE_DIR / f"{HANDLE}_events.jsonl"
headers = {"X-API-Key": API_KEY}
def load_json(p, default):
return json.loads(p.read_text()) if p.exists() else default
def save_json(p, obj):
p.write_text(json.dumps(obj))
def emit(d):
with OUT.open("a") as f:
f.write(json.dumps(d) + "\n")
def resolve_uid(handle):
r = requests.get(f"{BASE}/twitter/user/info",
params={"userName": handle}, headers=headers, timeout=10)
if r.status_code == 404:
return None # suspended / handle not found
r.raise_for_status()
return str(r.json()["data"]["id"])
def poll_once(uid):
r = requests.get(f"{BASE}/twitter/user/last_tweets",
params={"userId": uid}, headers=headers, timeout=10)
r.raise_for_status()
tweets = r.json().get("data", {}).get("tweets", [])
seen = set(load_json(IDS, []))
vel = load_json(VEL, [])
now = time.time()
engagements = []
for t in tweets:
if t["id"] in seen:
continue
e = (t.get("likeCount", 0) + t.get("retweetCount", 0) +
t.get("replyCount", 0))
emit({"kind": "new_tweet", "id": t["id"], "text": t.get("text"),
"first_seen_at": now, "engagement": e})
# schedule velocity re-checks
for m in VELOCITY_CHECKPOINTS:
vel.append({"tid": t["id"], "at": now + m * 60})
seen.add(t["id"]); engagements.append(e)
save_json(IDS, sorted(seen)[-300:])
save_json(VEL, vel)
# Simple spike alert (replace with Slack / PagerDuty / SES)
if engagements and len(seen) > 30:
# rolling median of recent engagement
recent = engagements + [e for e in load_json(STATE_DIR / f"{HANDLE}_eng.json", [])][-100:]
save_json(STATE_DIR / f"{HANDLE}_eng.json", recent[-100:])
if len(recent) >= 30:
median = statistics.median(recent)
for e in engagements:
if median > 0 and e > median * SPIKE_MULTIPLIER:
print(f"SPIKE: handle={HANDLE} engagement={e} median={median:.0f}")
def velocity_pass():
vel = load_json(VEL, [])
due = [c for c in vel if c["at"] <= time.time()]
rest = [c for c in vel if c["at"] > time.time()]
save_json(VEL, rest)
for c in due:
r = requests.get(f"{BASE}/twitter/tweet/info",
params={"tweetId": c["tid"]}, headers=headers, timeout=10)
if r.status_code == 404:
emit({"kind": "velocity_checkpoint", "id": c["tid"], "present": False})
else:
d = r.json().get("data", {})
emit({"kind": "velocity_checkpoint", "id": c["tid"], "present": True,
"likes": d.get("likeCount"), "retweets": d.get("retweetCount")})
if __name__ == "__main__":
uid = resolve_uid(HANDLE)
while True:
try:
if uid is None:
emit({"kind": "handle_inactive", "at": time.time()})
time.sleep(1800); uid = resolve_uid(HANDLE); continue
poll_once(uid); velocity_pass()
except Exception as e:
print("err:", e)
time.sleep(POLL_INTERVAL)
Questions readers ask
What's the cheapest way to monitor a Twitter / X account in 2026?
Timeline polling at 60-second intervals via a third-party X API like TwitterAPI.io. At their $0.00015 per read rate, a single account costs about $6.50/month end-to-end (1,440 reads/day × 30 days × $0.00015). The same workload on the official X API at $0.005/read costs about $216/month — the per-call gap is roughly 33×.
Polling vs streaming vs webhooks — which one should I use?
If your latency requirement is ≥ 60 seconds, use polling (simplest, cheapest, serverless-friendly). If you need sub-5-second freshness and don't want to run a persistent worker, use webhooks (stateless HTTP delivery). If you need sub-second freshness for high-stakes alerting (trading, brand-safety), use the filtered stream (persistent WebSocket). The single-line rule: pick the latency that matches your downstream urgency, then pick the cheapest path that hits it.
Can I monitor tweets without applying for X developer access?
Yes — through a third-party API like TwitterAPI.io, which uses an X-API-Key HTTP header instead of OAuth and skips the 1-2 week developer-platform application. The official X API path still requires the application + OAuth setup. If you want to ship a monitoring prototype this week, the third-party path is meaningfully faster.
What happens if my monitored account gets suspended or deactivated?
user/info returns 404. Treat this as state, not an error — flag your pipeline as handle_inactive and back off to a once-per-hour heartbeat check via user/info. Resume normal poll cadence when the handle resolves again. The Python script in this guide handles this branch automatically.
How do I detect tweet deletions in a monitoring pipeline?
Two layers. First, schedule engagement re-checks at T+15m, T+1h, T+6h, T+24h via tweet/info; any 404 at a checkpoint is a deletion event. Second, accept that sub-minute deletions are unreachable from polling — only the filtered stream captures every tweet before deletion. If you need a guaranteed-complete deletion archive, the stream is the only path.
What's the rate limit on monitoring via the X API?
Official X API has per-endpoint 15-minute caps (75-900 requests per 15 min depending on endpoint). TwitterAPI.io has no equivalent strict 15-minute window — instead, you get spending-limit control (set a maximum monthly spend in the dashboard). For 60-second monitoring of a single account, neither path's rate limit is binding; for high-fan-out monitoring (100+ accounts at 60-second cadence), the third-party path is far more predictable.
Is it legal to programmatically monitor public Twitter accounts?
Programmatic access to public tweets via the X API (official or third-party) is governed by the API's Terms of Service, not by per-account consent — public posts are available for public consumption and analysis under those terms. This is access to public data only; protected accounts are excluded. For commercial downstream uses (brand-safety products, social listening platforms, sentiment analytics), consult your jurisdiction's data-protection regulations on top of the API ToS.
Continue
- X API — TwitterAPI.io coverage hub
- Twitter monitoring — the broader pattern beyond single-account watching
- Twitter monitoring tools — third-party platform roundup
- X API cost breakdown — the per-call rate math behind the 33× gap
- Twitter rate-limit exceeded — why the official cap math matters at scale
- TwitterAPI.io pricing — per-call rates and volume tiers
Stop reading. Start building.
Starter credits cover real testing on real data. Google sign-in, no card, no application queue.
Get an API key