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 third-party path that is about 33× cheaper per read, 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: tweet/advanced_search with from:<handle> since_time:<unix seconds of the newest tweet seen>, 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 + /twitter/tweets 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 20 tweets per page. Use for discovery in hashtag, keyword, and mention trackers. Cost: $0.00015 per returned tweet on TwitterAPI.io ($0.00015 minimum per request, so a full 20-tweet page is $0.003); $0.005 per post read on official X API (Recent Search).
user/last_tweets — recent ~20 tweets for a specific user. Use for a one-off timeline fetch or back-fill, not for a recurring poll: every call returns the latest page again. Cost: $0.00015 per returned tweet, so a full ~20-tweet page is about $0.003 per call. For recurring account-based discovery, search from:<handle> since_time:<unix seconds of the newest tweet seen> instead.
/twitter/tweets (look-up by tweet ID) — full info for a specific tweet (engagement metrics, deletion check). Use for velocity capture and lifecycle monitoring. Cost: $0.00015 per tweet looked up by ID.
tweet_filter/add_rule (+ webhook or WebSocket) — real-time push delivery of tweets matching a filter. Sub-second freshness. Cost: $0.00015 per matched tweet plus a $0.00015 minimum per rule check, so the check interval sets the floor.
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 via a from:<handle> since_time: search adds about $5.40/month at an hourly poll (50 × 720 × $0.00015), plus $0.00015 per new tweet returned: a poll with nothing new returns 0 tweets and costs the 15-credit minimum ($0.00015), whereas a last_tweets poll bills every tweet on the page (about 20 tweets, so about $130 a month at 60 seconds). 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.
A tweet ID missing from the response at any checkpoint = deletion event, logged with the last-known engagement state.
Cost at the default cadence: 1-2 brand mentions plus 1-2 hashtag matches per minute is roughly 2,900-5,800 tweets a day. Discovery bills $0.00015 per tweet found (about $13-26/month), and the 4 /twitter/tweets checkpoints per tweet add about $52-104/month, so the total is roughly $65-130/month. Scales linearly with tweet volume.
To extend to account-based tracking, add one from:<handle> since_time: search per account in discover_pass() — see commented pattern at the bottom of the script. Seed each handle's since_time with the current time on the first run, then set it to one second after the newest tweet seen.
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 per-endpoint limits in 15-minute windows on tweets/search/recent (see docs.x.com for the current numbers), on top of a 3,000,000 post-read monthly cap on pay-per-use. For brand-monitoring at high volume, you'll hit this. TwitterAPI.io has no 15-minute windows and no monthly read cap; it limits requests per second instead (20 requests/s once paid, 50 on Scale, 500 on Business; HTTP 429 if exceeded, with no Retry-After header, so back off about a second and retry). Easier to reason about; cost scales linearly with volume.
Deletion handling. Some tweets get deleted within minutes of posting. Your tracker captures the tweet at discovery time, then the first velocity checkpoint that comes back without the tweet 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 by volume (4 velocity checkpoints per tracked tweet; discovery adds $0.00015 per tweet found on TwitterAPI.io, about 25% more):
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.
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("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/tweets",
params={"tweet_ids": c["tid"]}, headers=headers, timeout=10)
r.raise_for_status()
found = [t for t in r.json().get("tweets", []) if t.get("id")]
if not found: # not returned (or empty id) = deleted
emit({"kind": "deletion_detected", "id": c["tid"], "at": c["at"]})
continue
d = found[0]
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:
#
# from datetime import datetime
# ACCOUNTS = ["competitor1", "competitor2"]
# SINCE = {h: int(time.time()) for h in ACCOUNTS} # first run: start from now
# def to_unix(created_at): # createdAt looks like "Tue Oct 13 16:42:56 +0000 2026"
# return int(datetime.strptime(created_at, "%a %b %d %H:%M:%S %z %Y").timestamp())
# def discover_accounts():
# for handle in ACCOUNTS:
# # only tweets newer than the last one seen; an empty poll costs the 15-credit minimum
# r = requests.get(f"{BASE}/twitter/tweet/advanced_search",
# params={"query": f"from:{handle} since_time:{SINCE[handle]}",
# "queryType": "Latest"},
# headers=headers, timeout=10)
# r.raise_for_status()
# tweets = r.json().get("tweets") or []
# if tweets:
# SINCE[handle] = max(to_unix(t["createdAt"]) for t in tweets) + 1
# ... 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 does it cost 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 X API per-post read rates?
Via the official X API, every post you receive bills as a post read at $0.005 under pay-per-usage (1M posts = $5,000), and pay-per-usage stops at 3 million post reads per monthly billing cycle. 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 about 33× cheaper per read ($0.00015 vs $0.005).
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 comes back without the tweet, 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; on the official X API every streamed post bills as a $0.005 post read.
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
- 01Twitter (X) Statistics 2026: Attributed Figures and First-Hand Data on the Biggest Accounts
- 02Twitter (X) to SMS: Get a Text Message When an Account Posts
- 03Tweet Hunter (TweetHunter) Review: What It Automates, What It Costs, and the API Route for the Data Half
- 04How to Search Twitter (X) for Images: Operators, What They Return, and the API Route
- 05SOCMINT on Twitter (X): What Social Media Intelligence Is, and a Worked Method
- 06Twitter (X) Data Collection — A Developer's API Guide
- 07How to Quote a Tweet (Quote Post) on X
- 08How to Search for Deleted Tweets
Stop reading. Start building.
Starter credits cover real testing on real data. Google sign-in, no card, no application queue.
Get an API key