Social Media Tracking

Overview

Tracking is a best practice for getting more complete data from Xpoz. When you track a keyword, user, subreddit, or hashtag, Xpoz continuously collects data for those items in the background. This means:

• More complete data: Tracked items accumulate data over time, giving you a fuller picture than one-off queries.
• Better coverage: Continuous collection captures posts and activity that a single point-in-time query might miss.

You can track four types of items across platforms:

• Keywords — Track any phrase or topic (e.g., "AI agents", "your brand name"). Xpoz continuously collects posts matching these keywords across the platforms you specify.
• Users — Track specific accounts (e.g., a competitor, influencer, or your own brand handle). Xpoz collects their posts and activity.
• Subreddits (Reddit only) — Track entire subreddit communities to monitor discussions.
• Hashtags (TikTok only) — Track TikTok hashtags to follow trends and campaigns.

When to Use

• "Track mentions of [BRAND] across social media"
• "Set up monitoring for [KEYWORD] on Twitter and Reddit"
• "What keywords am I currently tracking?"
• "Add @competitor to my tracked users on Instagram"
• "Monitor #AIagents on TikTok"
• "Stop tracking [OLD KEYWORD]"
• "How many tracked items can I add?"

Step 1: Check Current Tracking

First, see what's already being tracked.

Via MCP

Call getTrackedItems

Via Python SDK

from xpoz import XpozClient

client = XpozClient()
items = client.tracking.get_tracked_items()
for item in items:
    print(f"[{item.platform}] {item.type}: {item.phrase}")
client.close()

Via TypeScript SDK

import { XpozClient } from "@xpoz/xpoz";

const client = new XpozClient();
await client.connect();
const items = await client.tracking.getTrackedItems();
items.forEach(item => console.log(`[${item.platform}] ${item.type}: ${item.phrase}`));
await client.close();

Via CLI

xpoz-cli tracking get_tracked_items

Present results as a table:

Platform	Type	Phrase
twitter	keyword	AI agents
instagram	user	competitor_brand
reddit	subreddit	machinelearning

Step 2: Add Tracked Items

Supported Types per Platform

Platform	keyword	user	subreddit	hashtag
Twitter	Yes	Yes	—	—
Instagram	Yes	Yes	—	—
Reddit	Yes	Yes	Yes	—
TikTok	Yes	Yes	—	Yes

Via MCP

Call addTrackedItems with items:
  [
    { "phrase": "AI agents", "type": "keyword", "platform": "twitter" },
    { "phrase": "AI agents", "type": "keyword", "platform": "reddit" },
    { "phrase": "competitor_user", "type": "user", "platform": "instagram" },
    { "phrase": "machinelearning", "type": "subreddit", "platform": "reddit" },
    { "phrase": "aitools", "type": "hashtag", "platform": "tiktok" }
  ]

Via Python SDK

client.tracking.add_tracked_items([
    {"phrase": "AI agents", "type": "keyword", "platform": "twitter"},
    {"phrase": "AI agents", "type": "keyword", "platform": "reddit"},
    {"phrase": "competitor_user", "type": "user", "platform": "instagram"},
    {"phrase": "machinelearning", "type": "subreddit", "platform": "reddit"},
    {"phrase": "aitools", "type": "hashtag", "platform": "tiktok"},
])

Via TypeScript SDK

await client.tracking.addTrackedItems([
  { phrase: "AI agents", type: "keyword", platform: "twitter" },
  { phrase: "AI agents", type: "keyword", platform: "reddit" },
  { phrase: "competitor_user", type: "user", platform: "instagram" },
  { phrase: "machinelearning", type: "subreddit", platform: "reddit" },
  { phrase: "aitools", type: "hashtag", platform: "tiktok" },
]);

Via CLI

xpoz-cli tracking add_tracked_items \
  --items '[{"phrase": "AI agents", "type": "keyword", "platform": "twitter"}, {"phrase": "AI agents", "type": "keyword", "platform": "reddit"}, {"phrase": "competitor_user", "type": "user", "platform": "instagram"}]'

Important: Call getAccountDetails to check available tracked item slots before adding.

Step 3: Remove Tracked Items

Via MCP

Call removeTrackedItems with items:
  [{ "phrase": "old keyword", "type": "keyword", "platform": "twitter" }]

Via Python SDK

client.tracking.remove_tracked_items([
    {"phrase": "old keyword", "type": "keyword", "platform": "twitter"},
])

Via TypeScript SDK

await client.tracking.removeTrackedItems([
  { phrase: "old keyword", type: "keyword", platform: "twitter" },
]);

Via CLI

xpoz-cli tracking remove_tracked_items \
  --items '[{"phrase": "old keyword", "type": "keyword", "platform": "twitter"}]'

Tip: Call getTrackedItems first to see exact phrases and platforms before removing.

Tracking Item Format

Field	Type	Description	Valid Values
phrase	string	The keyword, username, subreddit name, or hashtag to track	Any string
type	string	What kind of item	"keyword", "user", "subreddit" (Reddit only), "hashtag" (TikTok only)
platform	string	Which platform	"twitter", "instagram", "reddit", "tiktok"

Common Workflows

Track a Brand Across All Platforms

items: [
  { phrase: "YourBrand", type: "keyword", platform: "twitter" },
  { phrase: "YourBrand", type: "keyword", platform: "instagram" },
  { phrase: "YourBrand", type: "keyword", platform: "reddit" },
  { phrase: "YourBrand", type: "keyword", platform: "tiktok" },
  { phrase: "yourbrand", type: "user", platform: "twitter" },
  { phrase: "yourbrand", type: "user", platform: "instagram" }
]

Track Keywords for Market Research

items: [
  { phrase: "AI agents", type: "keyword", platform: "twitter" },
  { phrase: "AI agents", type: "keyword", platform: "reddit" },
  { phrase: "AI agents", type: "keyword", platform: "tiktok" },
  { phrase: "LLM tools", type: "keyword", platform: "twitter" },
  { phrase: "LLM tools", type: "keyword", platform: "reddit" }
]

Monitor a Competitor

items: [
  { phrase: "competitor_handle", type: "user", platform: "twitter" },
  { phrase: "competitor_handle", type: "user", platform: "instagram" },
  { phrase: "CompetitorName", type: "keyword", platform: "reddit" }
]

Track a Hashtag Campaign on TikTok

items: [
  { phrase: "yourcampaign", type: "hashtag", platform: "tiktok" },
  { phrase: "campaignvariant", type: "hashtag", platform: "tiktok" },
  { phrase: "your campaign", type: "keyword", platform: "twitter" }
]

Set Up Subreddit Monitoring

items: [
  { phrase: "machinelearning", type: "subreddit", platform: "reddit" },
  { phrase: "artificial", type: "subreddit", platform: "reddit" },
  { phrase: "LocalLLaMA", type: "subreddit", platform: "reddit" }
]

Notes

• Tracking vs one-shot queries: Tracking sets up continuous data collection for more comprehensive results. One-shot queries (like getTwitterPostsByKeywords) search existing cached data and may miss recent activity. Track items you care about for ongoing, complete data; use one-shot queries for ad-hoc research.
• Data completeness: Tracked items are crawled regularly, giving you more comprehensive data than untracked queries. This is especially impactful for fast-moving topics or competitive monitoring.
• Data availability: Tracked data accumulates over time. New tracked items won't have historical data — they start collecting from when you add them.

See Also

• xpoz-best-practices — query syntax, pagination, field selection, full auth docs
• social-sentiment-analyzer — analyze sentiment of tracked topics
• competitive-intel — compare brands you're tracking
• xpoz-getting-started — first-time setup and onboarding

Example Prompts

• "Track mentions of 'Claude Code' on Twitter and Reddit"
• "What am I currently tracking?"
• "Add @openai to my tracked users on Twitter"
• "Set up monitoring for our brand across all platforms"
• "Monitor #sustainability on TikTok"
• "Stop tracking 'old product name' on all platforms"
• "How many tracked items do I have left?"
• "Track the r/LocalLLaMA subreddit"