Twitter (X) Post Tracker via API — A Developer Guide
A 'post tracker' for Twitter (X) is a different shape of product from an account tracker. Where an account tracker watches a handle and captures everything it does, a post tracker takes specific tweets — selected by keyword, hashtag, mention, or list — and follows their performance over time. Engagement velocity in the first 15 minutes; total reach after 24 hours; deletion vs survival rate; viral spread network. Each tweet becomes a tracked entity with a lifecycle.
This guide is the developer version. It covers the X API endpoints needed (timeline poll + tweet/info re-fetch + advanced_search for keyword-based discovery), the runnable Python that combines them into a per-post tracking pipeline, the viral-detection threshold math that actually works (and the ones that don't), and the cost economics at realistic post-counts.
If you're building social-listening tooling, brand-safety alerting, content-performance analytics, or competitive intelligence around specific Twitter posts, this guide gives you the integration shape and the realistic cost numbers.
What 'tracking a post' actually means — three distinct operations
Be precise about what you're tracking. Three distinct operations get casually called 'post tracking':
1. Discovery — finding posts to track. You start with a query (a hashtag, a keyword, a user_id, a list of accounts) and the X API returns matching tweets. Discovery uses tweet/advanced_search for keyword/hashtag, user/last_tweets for account-based, or tweet_filter for real-time match.
2. Velocity capture — measuring engagement over time. For each discovered tweet, fetch its engagement at multiple time points (T+5m, T+30m, T+2h, T+24h) to capture the engagement-velocity curve. Uses tweet/info per re-fetch.
3. Lifecycle monitoring — detecting deletion or relationship changes. A tracked tweet may get deleted, quote-tweeted by others, or have its likes/RTs change as the platform's recommendation algorithm shifts. Detect via the same tweet/info re-fetch loop — 404 = deletion, count changes = recomputation.
Most production post trackers do all three. The runnable Python in the code section combines discovery (via account-based or keyword-based input) + velocity capture (T+15m/T+1h/T+6h/T+24h checkpoints) + deletion detection (404 = deletion event).
Discovery — how you find posts worth tracking
Four discovery patterns work in production. Pick based on what triggers your interest in a tweet.
A — Account-based discovery. You have a target account (or list of accounts); track every tweet they post. Uses user/last_tweets polled at 60-second cadence. Best for: monitoring specific accounts (competitors, news commentators, key customers).
B — Keyword/hashtag discovery. You have a keyword (brand name, hashtag, product term); track every tweet that mentions it. Uses tweet/advanced_search polled at 5-minute cadence (or filter stream for sub-minute). Best for: brand monitoring, sentiment analysis, campaign tracking.
C — Engagement-threshold discovery. You have a topic and care only about tweets that gain high engagement quickly. Combine keyword discovery + filter to tweets with > N likes/retweets in the first 30 minutes. Best for: viral-detection products, breaking-news alerting.
D — Reply/quote discovery. You have a known tweet; track all replies and quote tweets that respond to it. Uses tweet/quotes + tweet/replies for backfill; filter stream for real-time. Best for: discussion-network mapping, controversy tracking.
Cost note. Discovery is the cheapest part of the pipeline — one call returns up to 100 candidate tweets. Velocity capture (the per-tweet re-fetches) is what compounds at scale. Budget accordingly.
Velocity capture — when to re-fetch and what to record
The single highest-signal metric in post tracking is engagement velocity in the first 15-30 minutes after posting. Slope of likes/minute in that window is treated as a leading indicator of 24-hour final reach; the strength of the correlation depends on the account category and is best calibrated against your own observed data — typically a stronger signal than any single point-in-time count.
Recommended re-fetch schedule. Capture engagement at T+5m, T+15m, T+1h, T+6h, T+24h. Five checkpoints per tracked tweet; each is one tweet/info call.
Per-checkpoint cost. $0.00015 per call on TwitterAPI.io × 5 checkpoints = $0.00075 per tracked tweet end-to-end. At 1,000 tweets tracked per day, that's $0.75/day = ~$23/month.
Avoid more frequent checkpoints. A T+1m / T+2m / T+5m / T+10m schedule sounds better but the marginal signal is small (engagement at T+1m is usually 0 even on viral tweets) and the cost compounds. T+5m is the earliest meaningful checkpoint for most workloads.
Avoid less frequent checkpoints either. Just capturing T+24h misses the velocity curve entirely — you can't distinguish 'viral and slowing' from 'still building' from 'flat'. The slope between consecutive checkpoints is the metric that matters.
Viral-detection thresholds — what works and what doesn't
Three threshold approaches show up in real-world products. Two of them work; one mostly doesn't.
Works: rolling-median-multiplier. Compute the median engagement-velocity of the last N tracked tweets from the same source (account or keyword). A new tweet that exceeds 3× the median is a viral candidate. Adapts to baseline drift; works across account sizes.
Works: time-windowed-percentile. For each tweet, compute its T+15m engagement percentile vs the same source's last 100 tweets at the same checkpoint. Top-5% velocity is viral; top-1% is mega-viral. Better statistical foundation than median-multiplier.
Doesn't work: absolute thresholds. '> 1,000 likes in 15 minutes is viral' is the naive threshold. Doesn't work because (a) baseline velocity differs 100× across accounts (Elon Musk's median vs a 10K-follower account), (b) topic categories have different velocity profiles, (c) X's recommendation algorithm shifts baselines over time. Any absolute threshold is wrong for most accounts most of the time.
Recommended starting point. Rolling-median-multiplier × 3 with a minimum tweet count of 30 to seed the median. Switch to time-windowed-percentile once you have > 100 tweets per source for reliable statistics.
Deletion-archive logic — capturing what disappears
Tweet deletions matter for several use cases: tracking high-deletion-rate accounts (politicians, celebrities), measuring controversy (deleted tweets often indicate regret/correction), or building a forensic archive for journalism or compliance.
Detection approach. Same tweet/info re-fetch loop. A 404 at any checkpoint = the tweet has been deleted (or the account has gone private/suspended). Emit a deletion_detected event with the timestamp and the most recent engagement state.
Limitations. This detects deletions at the granularity of your re-fetch schedule (5 minutes to 24 hours). Sub-minute deletions are invisible unless you're using the filter stream to capture every tweet before deletion can land.
Practical note for high-deletion accounts. If a target account has a high deletion rate (some celebrity / political accounts can delete a substantial fraction of viral tweets), shift to using the filter stream for capture + your own archive — you'll catch the tweets that get deleted in the 5-minute window your polling doesn't cover.
Privacy and ToS note. Storing deleted tweets is in a legal gray area in some jurisdictions (the original poster's right to be forgotten vs the public-interest justification). For commercial / journalism / compliance use cases, consult counsel.
Cost economics — what tracking N posts per day actually costs
Cost scales with posts-tracked × checkpoints-per-post. Five checkpoints (T+5m/T+15m/T+1h/T+6h/T+24h) is the recommended baseline. Plus discovery cost (small for keyword-based, slightly higher for account-based).
Realistic monthly cost on TwitterAPI.io vs official X API at three scales:
The 33× cost gap holds end-to-end. At 1,000 posts tracked per day — realistic for a brand-monitoring SaaS or competitive-intelligence product — you pay $22.50/month on TwitterAPI.io vs $750 on the official path.
The fairness disclosure. This compares post-tracking workload only. If you also need first-party analytics (your own account's metrics), the official X API has analytics 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 — downstream applications
Once per-post tracking data is in your pipeline, several applications compose:
- Viral-detection alerting — Notify when a tweet matching your filter exceeds the rolling-median-multiplier threshold. The T+15m velocity is the alerting trigger; T+1h confirms.
- Content benchmarking — Compare engagement-velocity across different tweet shapes (text only / image / video / quote-tweet) on the same account. Different shapes can have substantially different velocity baselines — normalize before comparing rather than treating all shapes as comparable.
- Discussion-network mapping — Pull quote-tweet and reply graphs for high-velocity tweets; cluster the responders to map adjacent commentary networks. Useful for partnership identification and competitive positioning.
- Crisis detection (brand-safety) — Negative-sentiment tweets that hit viral-velocity thresholds in the first 30 minutes are early warning signals. Surface these to a brand's PR team within 60 seconds for fastest response.
- Content-experiment measurement — A/B test different tweet content with the same account; the engagement-velocity curve over the test population is the metric that matters (not final counts, which are confounded by initial reach randomness).
# pip install requests
import json
import time
import statistics
import pathlib
import requests
API_KEY = "YOUR_TWITTERAPI_IO_KEY"
BASE = "https://api.twitterapi.io"
KEYWORD = "YOUR_BRAND" # change to your tracked keyword
POLL_INTERVAL = 300 # 5 min discovery cadence
VELOCITY_CHECKPOINTS = [5, 15, 60, 360, 1440] # minutes after first-seen
SPIKE_MULTIPLIER = 3.0
STATE_DIR = pathlib.Path(".state")
STATE_DIR.mkdir(exist_ok=True)
IDS = STATE_DIR / f"posts_{KEYWORD}_seen.json"
VEL = STATE_DIR / f"posts_{KEYWORD}_queue.json"
VELS = STATE_DIR / f"posts_{KEYWORD}_velocities.json"
OUT = STATE_DIR / f"posts_{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_recent(keyword):
r = requests.get(f"{BASE}/twitter/tweet/advanced_search",
params={"queryType": "Latest", "query": keyword},
headers=headers, timeout=10)
r.raise_for_status()
return r.json().get("data", {}).get("tweets", [])
def fetch_tweet_info(tid):
r = requests.get(f"{BASE}/twitter/tweet/info",
params={"tweetId": tid}, headers=headers, timeout=10)
if r.status_code == 404:
return None # deleted
r.raise_for_status()
return r.json().get("data", {})
def rolling_median_baseline():
vs = load(VELS, [])
return statistics.median(vs) if len(vs) >= 30 else None
def record_velocity(v):
vs = load(VELS, [])[-99:] + [v]
save(VELS, vs)
def discover_pass():
seen = set(load(IDS, []))
queue = load(VEL, [])
now = time.time()
for t in discover_recent(KEYWORD):
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"),
"first_seen_at": now, "engagement": e})
for m in VELOCITY_CHECKPOINTS:
queue.append({"tid": t["id"], "at": now + m * 60, "first_seen": now})
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:
info = fetch_tweet_info(c["tid"])
if info is None:
emit({"kind": "deletion_detected", "id": c["tid"], "at": c["at"]})
continue
e = info.get("likeCount", 0) + info.get("retweetCount", 0) + info.get("replyCount", 0)
elapsed_min = (c["at"] - c["first_seen"]) / 60.0
velocity = e / max(elapsed_min, 1) # engagement per minute
emit({"kind": "velocity_checkpoint", "id": c["tid"], "at": c["at"],
"elapsed_min": elapsed_min, "engagement": e, "velocity": velocity})
# Spike detection at first checkpoint (~T+5m or T+15m)
if elapsed_min < 30:
record_velocity(velocity)
baseline = rolling_median_baseline()
if baseline and velocity > baseline * SPIKE_MULTIPLIER:
emit({"kind": "viral_alert", "id": c["tid"],
"velocity": velocity, "baseline": baseline})
print(f"VIRAL: tweet {c['tid']} velocity={velocity:.1f} (baseline {baseline:.1f})")
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 tracking a Twitter account vs tracking a Twitter post?
Account tracking watches a handle and captures everything it does (tweets, replies, retweets, follower changes) — uses user/last_tweets etc. Post tracking takes specific tweets (by keyword, hashtag, mention, or selection) and follows their performance over time — engagement velocity, viral detection, deletion archive. Different shapes of product; both can use the same underlying API surface.
What's the strongest predictor of whether a tweet will go viral?
Engagement velocity in the first 15-30 minutes — likes-plus-retweets per minute. Treated by practitioners as a leading indicator of viral potential; the strength of correlation varies by account category, so calibrate against your own historical data rather than relying on a fixed threshold. The Python script in this guide implements rolling-median-multiplier × 3 as a starting threshold.
How often should I re-fetch tracked tweets for engagement metrics?
Five checkpoints per tweet: T+5m / T+15m / T+1h / T+6h / T+24h. More frequent (T+1m) is wasted (engagement at T+1m is usually 0). Less frequent (just T+24h) misses the velocity curve. The slope between consecutive checkpoints is the metric that matters; you need at least 3-4 checkpoints in the first hour to compute it reliably.
How do I detect when a tracked post gets deleted?
Re-fetch via tweet/info at each velocity checkpoint. A 404 response means the tweet has been deleted (or the account suspended / gone private). Emit a deletion_detected event. Detection granularity = your re-fetch schedule (5-15 min minimum); sub-minute deletions are only catchable via the filter stream that captures every tweet at post time.
How much does tracking 1,000 posts per day cost via API?
On TwitterAPI.io at $0.00015 per read with 5 velocity checkpoints per tweet, tracking 1,000 posts/day costs about $22.50/month. On the official X API at $0.005 per read, the same workload costs about $750/month. The 33× gap holds end-to-end at all scales tested.
What's a realistic viral-detection threshold?
Rolling-median-multiplier × 3 with a minimum tweet count of 30 to seed the median. Tweet exceeds 3× the median engagement-velocity of the last 100 tracked tweets from the same source = viral candidate. Switch to time-windowed-percentile (top-5% velocity) once you have > 100 tweets per source for reliable statistics. Don't use absolute thresholds ('1,000 likes in 15 min'); they're wrong for most accounts most of the time.
Continue
- X API — TwitterAPI.io coverage hub
- Twitter account views tracking — sibling account-level metric guide
- Twitter follower tracking — sibling follower-graph guide
- Monitoring Twitter via API — broader real-time architecture patterns
- 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