Building a Tweet Tracker via API — A Developer Guide
Most 'tweet tracker' search results point to consumer dashboards — log in, paste a hashtag, get a report. Useful if that's what you need. If you're building software, you need something different: the architecture and runnable code to track tweets at production scale, with control over the data shape, alerting logic, and cost economics.
This guide is for developers. It covers the four kinds of tweet tracker you might build (account-based, hashtag-based, mention-based, engagement-threshold), the X API endpoints for each, the runnable Python that pulls them together, and the cost numbers at 100 / 1,000 / 10,000 tracked tweets per day. Plus the operational realities — deletions, suspensions, rate limits, alerting design — that the marketing pages don't cover.
By the end, you'll have a working tracker pattern, a 33×-cost-cheaper third-party path, and the decision framework to pick the right architecture for your specific use case.
Four types of tweet tracker — pick the right one before coding
The word 'tweet tracker' covers four architecturally distinct products. Pick the wrong one and your code structure won't fit.
1. Account-based tracker. You watch specific user handles; capture every tweet they post. Discovery endpoint: user/last_tweets polled at 60-second cadence. Best for: monitoring competitors, key opinion leaders, customer-facing accounts.
2. Hashtag / keyword tracker. You watch specific hashtags or terms; capture every tweet that mentions them. Discovery endpoint: tweet/advanced_search polled at 5-minute cadence. Best for: brand monitoring, campaign tracking, topic research.
3. Mention tracker. You watch your brand handle and capture every tweet that @-mentions it. Discovery: tweet/advanced_search with to:yourhandle operator. Best for: customer support detection, brand engagement.
4. Engagement-threshold tracker. You watch a topic + filter to only tweets that reach engagement thresholds (e.g., > 100 likes in 30 minutes). Discovery + tweet/info re-fetch with threshold. Best for: viral-detection products, breaking-news alerting.
Most production trackers combine 2-3 of these. A brand-safety platform might do hashtag tracking (to catch brand mentions in unbranded posts) + mention tracking (to catch direct mentions) + engagement-threshold (to prioritize viral content). The runnable Python in the code section starts with hashtag + mention; account-based and threshold logic are commented patterns to extend.
The X API endpoints — what each one returns and what it costs
Four endpoints get used in tweet tracking. Worth knowing the names upfront for cost estimation and rate-limit math.
tweet/advanced_search — keyword/hashtag/operator search returning up to 100 tweets per call. Use for discovery in hashtag, keyword, and mention trackers. Cost: $0.00015 per call on TwitterAPI.io; $0.005 per call on official X API (Recent Search).
user/last_tweets — recent ~20 tweets for a specific user. Use for account-based discovery. Cost: $0.00015 per call.
tweet/info — full info for a specific tweet (engagement metrics, deletion check). Use for velocity capture and lifecycle monitoring. Cost: $0.00015 per call.
tweet_filter/add_rule (+ webhook or WebSocket) — real-time push delivery of tweets matching a filter. Sub-second freshness. Cost: per matched tweet delivered.
Cost compounds at scale. Discovery is cheap per call; the per-tweet velocity-capture compounds. A keyword tracker that finds 100 tweets/day and re-fetches 5 times each = 500 calls/day = ~$2.25/month for the entire tracker. Adding account-based discovery on 50 accounts adds another ~$45/month. Scale economics are linear and predictable — the third-party path's per-call rate is the dominant cost factor.
Runnable Python — combined hashtag + mention + velocity tracker
Below is a working Python tracker that combines hashtag and mention discovery + per-tweet velocity capture. Configure your keyword and brand handle at the top; the script polls every 5 minutes, dedupes against local state, captures engagement at T+15m / T+1h / T+6h / T+24h, and outputs structured JSONL.
Implementation notes:
- Discovery runs every 5 minutes via tweet/advanced_search with combined query (#{KEYWORD} OR (to:{HANDLE} OR @{HANDLE})).
- New tweets get scheduled velocity re-fetches at 4 checkpoints.
- Re-fetch loop runs every poll tick; checks the queue for due checkpoints.
- 404 at any checkpoint = deletion event, logged with the last-known engagement state.
- Cost at the default cadence: ~$5/month for moderate-volume tracking (1-2 brand mentions per minute + 1-2 hashtag matches per minute). Scales linearly with tweet volume.
- To extend to account-based tracking, add user/last_tweets calls per account in discover_pass() — see commented pattern at the bottom of the script.
Operational considerations — what determines whether your tracker works in production
Three operational factors that decide success once you're past the prototype:
Rate-limit behavior. Official X API enforces 180-450 requests per 15 minutes on tweets/search/recent (Free / Basic tier). For brand-monitoring at high volume, you'll hit this. TwitterAPI.io uses spending-limit control instead — no 15-minute window. Easier to reason about; predictable cost ceiling.
Deletion handling. Some tweets get deleted within minutes of posting. Your tracker captures the tweet at discovery time, then a 404 at the first velocity checkpoint reveals the deletion. Emit a deletion_detected event with the original tweet's text and last-known engagement. For high-deletion-rate topics (politics, celebrities), consider supplementing polling with the filter stream to catch sub-minute deletions.
Alerting design — the most underappreciated dimension. A tracker that fires 1000 alerts a day is worse than no tracker. Tune your alerting thresholds (rolling-median-multiplier × 3 is a sane starting point), batch alerts by source, route high-velocity tweets to a separate higher-urgency channel. The Python script in the section above has the spike-detection logic commented in; production extension is a 20-line job.
Cost economics — what tracking N tweets per day actually costs
Realistic monthly cost on TwitterAPI.io vs official X API at three volume tiers (discovery + 4 velocity checkpoints per tracked tweet):
The 33× cost gap holds end-to-end. At 10,000 tweets tracked per day — realistic for an enterprise brand-monitoring product — you pay $180/month on TwitterAPI.io vs $6,000/month on the official path.
The honest framing. This compares tracker workload only. If your product also needs first-party analytics (your own account metrics) or PowerTrack-level real-time filtering, the official X API exposes endpoints not available via third-party; that's a separate workload with its own cost. See [our X API cost breakdown for the full picture](/blog/x-api-cost-breakdown-2026).
What the data unlocks — production applications
A working tweet tracker composes well with downstream applications:
- Brand-safety alerting — Tweets that mention your brand and exceed engagement-velocity thresholds in 30 minutes are early warning signals. Route to PR team within 60 seconds.
- Crisis monitoring — Negative-sentiment tweets that hit viral velocity on a hashtag relevant to your industry. Track sentiment via the runnable Python + a classifier; alert on high-velocity + negative.
- Customer support detection — Tweets that mention your brand handle with a question or complaint pattern. Route to support team based on detected intent.
- Competitive intelligence — Track competitor mentions; correlate with their own posts; spot momentum changes in their topic clusters.
- Content-experiment measurement — Track your own tweets' velocity to compare different content shapes (text vs image vs video, etc.). The velocity curve is the metric that matters; final counts are confounded by initial reach randomness.
# pip install requests
import json
import time
import pathlib
import requests
API_KEY = "YOUR_TWITTERAPI_IO_KEY"
BASE = "https://api.twitterapi.io"
KEYWORD = "YOUR_BRAND_KEYWORD"
HANDLE = "yourhandle" # for mention tracking
POLL_INTERVAL = 300 # 5 min
VELOCITY_CHECKPOINTS = [15, 60, 360, 1440] # minutes after first-seen
STATE_DIR = pathlib.Path(".state")
STATE_DIR.mkdir(exist_ok=True)
IDS = STATE_DIR / f"{KEYWORD}_seen.json"
VEL = STATE_DIR / f"{KEYWORD}_queue.json"
OUT = STATE_DIR / f"{KEYWORD}_events.jsonl"
headers = {"X-API-Key": API_KEY}
def load(p, d): return json.loads(p.read_text()) if p.exists() else d
def save(p, o): p.write_text(json.dumps(o))
def emit(d):
with OUT.open("a") as f: f.write(json.dumps(d) + "\n")
def discover_pass():
"""Search for new tweets matching keyword OR @-mention of brand."""
query = f'#{KEYWORD} OR (to:{HANDLE} OR @{HANDLE})'
r = requests.get(f"{BASE}/twitter/tweet/advanced_search",
params={"queryType": "Latest", "query": query},
headers=headers, timeout=10)
r.raise_for_status()
tweets = r.json().get("data", {}).get("tweets", [])
seen = set(load(IDS, []))
queue = load(VEL, [])
now = time.time()
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": "discovered", "id": t["id"], "text": t.get("text"),
"author": (t.get("author") or {}).get("userName"),
"created_at": t.get("createdAt"), "first_seen_at": now,
"engagement": e})
for m in VELOCITY_CHECKPOINTS:
queue.append({"tid": t["id"], "at": now + m * 60})
seen.add(t["id"])
save(IDS, sorted(seen)[-500:])
save(VEL, queue)
def velocity_pass():
queue = load(VEL, [])
due = [c for c in queue if c["at"] <= time.time()]
save(VEL, [c for c in queue if c["at"] > time.time()])
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": "deletion_detected", "id": c["tid"], "at": c["at"]})
continue
r.raise_for_status()
d = r.json().get("data", {})
emit({"kind": "velocity_checkpoint", "id": c["tid"], "at": c["at"],
"likes": d.get("likeCount"),
"retweets": d.get("retweetCount"),
"replies": d.get("replyCount")})
# Optional extension — add account-based discovery for a list of handles:
#
# ACCOUNTS = ["competitor1", "competitor2"]
# def discover_accounts():
# for handle in ACCOUNTS:
# uid = resolve_uid(handle) # cache locally
# r = requests.get(f"{BASE}/twitter/user/last_tweets",
# params={"userId": uid}, headers=headers, timeout=10)
# ... add new tweets to the same emit() + queue logic above ...
if __name__ == "__main__":
while True:
try:
discover_pass(); velocity_pass()
except Exception as e:
print("err:", e)
time.sleep(POLL_INTERVAL)
Questions readers ask
What's the difference between a tweet tracker and a Twitter monitoring tool?
A tweet tracker typically captures specific tweets (by keyword, hashtag, account, or mention) and follows their performance over time. A Twitter monitoring tool is broader — it might include account watching, sentiment dashboards, alerting workflows, and reporting features. Tracker is one architectural primitive; monitoring tool is a product built on top of tracker(s) + dashboards + workflows.
What's the cheapest way to track 1,000 tweets per day via API?
On TwitterAPI.io at $0.00015 per read with 4 velocity checkpoints per tweet, tracking 1,000 tweets/day costs about $18/month. On the official X API at $0.005/read the same workload costs about $600/month — a 33× gap. Both return the same data shape for standard tweet/search endpoints.
Can I track tweets in real time without paying for X API Pro tier?
Via the official X API, real-time filtered stream is Pro tier ($5,000/month). Via TwitterAPI.io, real-time delivery (webhook + WebSocket via oapi/tweet_filter/add_rule) is available without paid-plan gating. For sub-second freshness on tracked tweets, the third-party path is the cheaper option by orders of magnitude.
How do I handle tweets that get deleted right after being tracked?
Your tracker captures the tweet at discovery time (text + engagement state). When the first velocity-checkpoint re-fetch returns 404, emit a deletion_detected event with the captured text and last-known engagement. For sub-minute deletions, supplement polling with the filter stream — it captures every tweet at post time, regardless of subsequent deletion.
Should I poll or use the filter stream for tweet tracking?
Use polling if your latency requirement is ≥ 60 seconds and you want to keep operational complexity low (runs on cron, no persistent worker). Use filter stream (or webhooks) if you need sub-minute latency for alerting products. The TwitterAPI.io filter stream is the lower-cost option of the two real-time paths; the official X API filter stream requires Pro tier.
Can I track replies and quote tweets in addition to the original tweet?
Yes. Use tweet/replies to fetch a tweet's reply tree and tweet/quotes to fetch quote-tweets. Both endpoints are paginated; expect 5-20 calls per tracked viral tweet to fully expand the reply/quote graph. Useful for discussion-network mapping and controversy tracking.
Continue
- X API — TwitterAPI.io coverage hub
- Twitter post tracker — sibling per-post tracking guide
- Twitter follower tracking — sibling account-graph tracking
- Monitoring Twitter via API — broader real-time architecture
- X API cost breakdown — per-call rate math at scale
- TwitterAPI.io pricing — per-call rates
Stop reading. Start building.
Starter credits cover real testing on real data. Google sign-in, no card, no application queue.
Get an API key