Xpoz

Social media intelligence tools for Twitter/X, Instagram, Reddit, and TikTok. Access user profiles, posts, comments, engagement data, and keyword search across platforms.

Source

3 skills

xpoz-best-practices

Reference guide for using Xpoz effectively. Load this skill whenever working with Xpoz MCP tools — it ensures correct query syntax, optimal field selection, proper pagination, and best practices for every Xpoz interaction. Covers authentication, query syntax (boolean operators, date filtering), response modes (fast/paging/CSV), field selection, tracking setup, and all platform tool references (Twitter, Instagram, Reddit, TikTok). Use for ANY Xpoz-related work, not just explicit best-practices questions.

# Xpoz Best Practices

## Overview

Xpoz is a social media intelligence platform providing access to **Twitter/X**, **Instagram**, **Reddit**, and **TikTok** data through 48 MCP tools — no social media API keys required.

## When to Use

Load this skill for **any Xpoz interaction** — not just when the user explicitly asks about best practices. It provides the context needed to use Xpoz tools correctly:

- Calling any Xpoz MCP tool (query syntax, field selection, response modes)
- Setting up authentication or tracking
- Troubleshooting errors or empty results
- Choosing which tool to use for a specific task

## Quick Start

The Xpoz MCP server should already be configured by the plugin. If not, run `/xpoz-setup`.

See **[references/authentication.md](references/authentication.md)** for detailed auth flows and troubleshooting.

## Query Syntax

All keyword search tools support boolean query syntax:

| Operator | Example | Effect |
|----------|---------|--------|
| Exact phrase | `"machine learning"` | Matches exact phrase |
| OR | `"AI" OR "artificial intelligence"` | Matches either term |
| AND | `"Tesla" AND "earnings"` | Matches both terms |
| Grouping | `("deep learning" OR "neural network") AND python` | Combines operators |

**Date filtering:** Use `startDate` / `endDate` in YYYY-MM-DD format. Omit to use defaults (varies by tool).

**Content filtering** (Twitter only): Set `filterOutRetweets: true` to exclude retweets.

**Forbidden in query string:** `from:`, `to:`, `lang:`, `since:`, `until:`, `filter:` — use dedicated parameters instead.

## Platform Quick Reference

### Twitter/X (13 tools)
| Tool | Purpose |
|------|---------|
| `getTwitterUser` / `getTwitterUsers` | Look up 1-100 users by ID or username |
| `searchTwitterUsers` | Fuzzy search users by name |
| `getTwitterUserConnections` | Get followers or following |
| `getTwitterUsersByKeywords` | Find users who posted about a topic |
| `getTwitterPostsByIds` | Get 1-100 posts by ID |
| `getTwitterPostsByAuthor` | Get all posts from a username |
| `getTwitterPostsByKeywords` | Search posts by keywords |
| `getTwitterPostRetweets` | Get retweets of a post |
| `getTwitterPostQuotes` | Get quote tweets of a post |
| `getTwitterPostComments` | Get replies to a post |
| `getTwitterPostInteractingUsers` | Get commenters, quoters, or retweeters |
| `countTweets` | Count tweets matching a phrase |

See **[references/twitter.md](references/twitter.md)** for all parameters, fields, and examples.

### Instagram (9 tools)
| Tool | Purpose |
|------|---------|
| `getInstagramUser` | Look up user by ID or username |
| `searchInstagramUsers` | Fuzzy search users by name |
| `getInstagramUserConnections` | Get followers or following |
| `getInstagramUsersByKeywords` | Find users who posted about a topic |
| `getInstagramPostInteractingUsers` | Get commenters or likers of a post |
| `getInstagramPostsByIds` | Get posts by strong_id |
| `getInstagramPostsByUser` | Get posts from a user |
| `getInstagramPostsByKeywords` | Search posts by keywords in captions/subtitles |
| `getInstagramCommentsByPostId` | Get comments on a post |

See **[references/instagram.md](references/instagram.md)** for all parameters, fields, and examples.

### Reddit (9 tools)
| Tool | Purpose |
|------|---------|
| `getRedditUser` | Look up user by username |
| `searchRedditUsers` | Fuzzy search users by name |
| `getRedditUsersByKeywords` | Find users who posted about a topic |
| `getRedditPostsByKeywords` | Search posts by keywords |
| `getRedditPostWithCommentsById` | Get a post with all its comments |
| `getRedditCommentsByKeywords` | Search comments by keywords |
| `searchRedditSubreddits` | Search subreddits by name |
| `getRedditSubredditWithPostsByName` | Get subreddit details with posts |
| `getRedditSubredditsByKeywords` | Search subreddits by keyword in description |

See **[references/reddit.md](references/reddit.md)** for all parameters, fields, and examples.

### TikTok (9 tools)
| Tool | Purpose |
|------|---------|
| `getTiktokUser` | Look up user by ID or username |
| `searchTiktokUsers` | Fuzzy search users by name |
| `getTiktokUsersByKeywords` | Find users who posted about a topic |
| `getTiktokUsersByHashtags` | Find users who used specific hashtags |
| `getTiktokPostsByIds` | Get posts by ID |
| `getTiktokPostsByUser` | Get posts from a user |
| `getTiktokPostsByKeywords` | Search posts by keywords |
| `getTiktokPostsByHashtags` | Search posts by hashtags |
| `getTiktokCommentsByPostId` | Get comments on a post |

See **[references/tiktok.md](references/tiktok.md)** for all parameters, fields, and examples.

## Tracking

Setting up tracking is a best practice for getting more complete data from Xpoz. Tracked items are crawled regularly in the background, which means:

- **Better coverage** — continuous collection captures posts and activity that a single point-in-time query might miss
- **More complete data** — tracked items accumulate data over time, giving you a fuller picture than one-off queries

Track keywords, users, subreddits, and hashtags across all 4 platforms.

**Supported types per platform:**

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

**View current tracking:**
```
Call getTrackedItems
```

**Add tracked items:**
```
Call addTrackedItems with items:
  [{ phrase: "AI agents", type: "keyword", platform: "twitter" }]
```

**Remove tracked items:**
```
Call removeTrackedItems with items:
  [{ phrase: "AI agents", type: "keyword", platform: "twitter" }]
```

See **[xpoz-social-tracking](../xpoz-social-tracking/SKILL.md)** for full tracking workflows and advanced patterns.

## Response Modes

All paginated tools support three response modes via `responseType`:

| Mode | Behavior | Best For |
|------|----------|----------|
| `"fast"` (default) | Returns up to 300 results immediately | Quick lookups, exploration |
| `"paging"` | Async — returns `operationId`, poll with `checkOperationStatus` | Large datasets, page-by-page |
| `"csv"` | Async CSV export to S3 — returns download URL | Bulk export, offline analysis |

See **[references/pagination-and-export.md](references/pagination-and-export.md)** for async polling patterns, pagination, and CSV export details.

## Field Selection

Pass `fields` to request only the data you need. This reduces response size and improves performance.

```
Call getTwitterPostsByKeywords with:
  query: "AI agents"
  fields: ["id", "text", "authorUsername", "likeCount"]
```

Each platform has different available fields — see the platform-specific references for complete field lists.

## Common Patterns

**Search → Analyze → Export:**
1. Search posts by keywords (fast mode) to preview results
2. Analyze engagement, sentiment, or themes
3. Export full dataset to CSV for deeper analysis

**Find Users → Get Their Posts → Analyze:**
1. Search users by keywords to find relevant accounts
2. Get posts by author for top accounts
3. Analyze content patterns, posting frequency, engagement

**Data Freshness:**
- Data is cached in Xpoz's database with automatic API fallback when stale — results are kept fresh automatically
- Use `forceLatest: true` to bypass cache and force a live fetch (increases latency and cost)

## Troubleshooting

| Problem | Solution |
|---------|----------|
| "Unauthorized" | Verify token — run `/xpoz-setup` |
| Empty results | Check query syntax, widen date range, try different keywords |
| Stale data | Use `forceLatest: true` to bypass cache |
| Operation timeout | Keep polling `checkOperationStatus` every ~5s until status is no longer `running` |

## Detailed Guides

For complete parameters, response fields, patterns, and examples:

- **[references/authentication.md](references/authentication.md)** — Auth flows for MCP and SDK
- **[references/pagination-and-export.md](references/pagination-and-export.md)** — Response modes, operationId polling, CSV export, field selection
- **[references/twitter.md](references/twitter.md)** — All 13 Twitter tools with parameters, fields, and examples
- **[references/instagram.md](references/instagram.md)** — All 9 Instagram tools with parameters, fields, and examples
- **[references/reddit.md](references/reddit.md)** — All 9 Reddit tools with parameters, fields, and examples
- **[references/tiktok.md](references/tiktok.md)** — All 9 TikTok tools with parameters, fields, and examples
- **[references/sdk.md](references/sdk.md)** — Python & TypeScript SDK reference

## Example Prompts

- "How do I search for tweets about AI?"
- "What fields are available for Instagram posts?"
- "How do I export Reddit data to CSV?"
- "Set up tracking for my brand across all platforms"
- "How do I paginate through large result sets?"
- "What's the difference between fast mode and paging mode?"
- "Show me all available TikTok tools"

xpoz-getting-started

Get started with Xpoz — set up MCP connection, verify your account, configure tracking, and discover available tools. Use when asked to "set up Xpoz", "connect to Xpoz", "get started with Xpoz", "what can Xpoz do", "new to Xpoz", "install Xpoz", or "my Xpoz account".

# Getting Started with Xpoz

## Overview

Xpoz is a social media intelligence platform providing access to Twitter/X, Instagram, Reddit, and TikTok data — no social media API keys required. This plugin connects Cursor to Xpoz via MCP, giving you 48 tools for searching posts, looking up users, tracking keywords, and exporting data.

## When to Use

Activate when the user asks:
- "Help me set up Xpoz"
- "What's my Xpoz account status?"
- "Connect to Xpoz social media data"
- "What can I do with Xpoz?"
- "Set up tracking for my brand"
- "I'm new to Xpoz, where do I start?"

## Step 1: Check MCP Connection

Try calling `checkAccessKeyStatus` to verify the Xpoz MCP server is connected.

If it returns `hasAccessKey: true`, skip to **Step 3**.

## Step 2: Configure MCP Connection

If the MCP server is not connected, guide the user:

### Get an Access Token

Ask the user:
> "Go to https://xpoz.ai/get-token (free, no credit card) and paste the token here."

**WAIT for the user to reply with the token.** Do not proceed until they respond.

### Add to Cursor MCP Settings

Add this to Cursor's MCP settings (`~/.cursor/mcp.json` or via Cursor Settings → MCP):

```json
{
  "mcpServers": {
    "xpoz": {
      "url": "https://mcp.xpoz.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_HERE"
      }
    }
  }
}
```

Replace `YOUR_TOKEN_HERE` with the token from the user.

After saving, reload Cursor or restart the MCP server.

### Auth Errors

| Problem | Solution |
|---------|----------|
| "Unauthorized" | Verify token at [xpoz.ai/settings](https://xpoz.ai/settings) |
| Token exchange fails | Ask user to re-authorize — codes are single-use |

## Step 3: Verify Your Setup

Call `getAccountDetails` to retrieve the user's account information. Present a summary:

```
## Your Xpoz Account

**Plan:** [plan name]
**Billing period:** [start] – [end]
**Next renewal:** [date]

### Usage
- Subscription credits remaining: [X]
- Extra credits: [X]
- Tracked items: [X] / [limit]
```

## Step 4: Set Up Tracking

Setting up tracking is highly recommended — it's a best practice for getting more complete data. Tracked items are crawled regularly, so your search results have better coverage and capture activity that one-off queries might miss. Walk the user through their first tracked items.

Ask:
> "What would you like to monitor? For example:
> - Your brand name as a keyword across all platforms
> - A competitor's account on Twitter/Instagram
> - A relevant hashtag on TikTok
> - A subreddit in your niche"

**WAIT for the user to reply.** Do not proceed until they respond.

### Supported types per platform

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

### Example — add tracked items

```
Call addTrackedItems with items:
  [{ phrase: "your brand", type: "keyword", platform: "twitter" },
   { phrase: "your brand", type: "keyword", platform: "reddit" },
   { phrase: "competitor_username", type: "user", platform: "instagram" }]
```

Call `getAccountDetails` to check available tracked item slots.

See [xpoz-social-tracking](../xpoz-social-tracking/SKILL.md) for advanced tracking workflows.

## Step 5: What Can You Do?

### Platform Capabilities

| Platform | Users | Posts | Comments | Connections | Interactions | Special |
|----------|-------|-------|----------|-------------|--------------|---------|
| Twitter | lookup, search, by keywords | by ID, author, keywords | replies | followers/following | commenters/quoters/retweeters | countTweets |
| Instagram | lookup, search, by keywords | by ID, user, keywords | by post | followers/following | commenters/likers | strong_id format |
| Reddit | lookup, search, by keywords | by keywords, with comments | by keywords | — | — | subreddit search/lookup |
| TikTok | lookup, search, by keywords, by hashtags | by ID, user, keywords, hashtags | by post | — | — | hashtag search |

### Try It Now

Quick example to try immediately:

```
Call getTwitterPostsByKeywords:
  query: "AI agents"
  fields: ["id", "text", "authorUsername", "likeCount"]
```

## If the MCP Server is Not Connected

If any Xpoz MCP tool is unavailable, **stop immediately**. Tell the user:

1. The Xpoz MCP server is not connected
2. Run `/xpoz-setup` to configure and verify the connection
3. Then retry their request

## Example Prompts

- "Help me set up Xpoz"
- "What's my Xpoz account status?"
- "Connect to Xpoz social media data"
- "What can I do with Xpoz?"
- "Set up tracking for my brand"
- "I'm new to Xpoz, where do I start?"

xpoz-social-tracking

Set up and manage social media tracking across Twitter, Instagram, Reddit, and TikTok using Xpoz. Add, remove, and view tracked keywords, users, subreddits, and hashtags. Use when asked to "track mentions", "monitor brand", "set up tracking", "add tracked item", "what am I tracking", "stop tracking", "remove tracked", or "social monitoring".

# 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.

```
Call getTrackedItems
```

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 |

```
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" }
  ]
```

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

## Step 3: Remove Tracked Items

```
Call removeTrackedItems with 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](../xpoz-best-practices/SKILL.md) — query syntax, pagination, field selection, full auth docs
- [xpoz-getting-started](../xpoz-getting-started/SKILL.md) — 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"