Xpoz Best Practices

Overview

Xpoz is a social media intelligence platform providing access to Twitter/X, Instagram, Reddit, and TikTok data through MCP tools, Python SDK, TypeScript SDK, and CLI — 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)
• Writing code with the Python or TypeScript SDK
• Using the Xpoz CLI
• Setting up authentication or tracking
• Troubleshooting errors or empty results
• Choosing which tool to use for a specific task

Quick Start

MCP — add the Xpoz MCP server to your agent's config. The server URL is https://mcp.xpoz.ai/mcp. Most MCP clients handle OAuth automatically on first tool call.

Example for Claude Code (~/.claude.json):

{
  "mcpServers": {
    "xpoz": {
      "url": "https://mcp.xpoz.ai/mcp",
      "transport": "streamable-http"
    }
  }
}

Python SDK:

pip install xpoz

from xpoz import XpozClient
client = XpozClient()  # reads XPOZ_API_KEY env var
results = client.twitter.search_posts("artificial intelligence")
print(f"Found {results.pagination.total_rows:,} tweets")
client.close()

TypeScript SDK:

npm install @xpoz/xpoz

import { XpozClient } from "@xpoz/xpoz";
const client = new XpozClient();
await client.connect();
const results = await client.twitter.searchPosts("artificial intelligence");
console.log(`Found ${results.pagination.totalRows.toLocaleString()} tweets`);
await client.close();

CLI:

pip install xpoz-cli
xpoz-cli twitter search_posts --query "artificial intelligence" --limit 20

See [references/authentication.md](references/authentication.md) for detailed auth flows (MCP, SDK, CLI). See [references/sdk.md](references/sdk.md) for complete Python & TypeScript SDK reference. See [references/cli.md](references/cli.md) for CLI installation, commands, and rendering modes.

Query Syntax

All keyword search tools support boolean query syntax:

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)

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

Instagram (9 tools)

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

Reddit (9 tools)

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

TikTok (9 tools)

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:

View current tracking:

MCP:        call getTrackedItems
Python:     client.tracking.get_tracked_items()
TypeScript: await client.tracking.getTrackedItems()
CLI:        xpoz-cli tracking get_tracked_items

Add tracked items:

MCP:        call addTrackedItems with items: [{ phrase: "AI agents", type: "keyword", platform: "twitter" }]
Python:     client.tracking.add_tracked_items([{ "phrase": "AI agents", "type": "keyword", "platform": "twitter" }])
TypeScript: await client.tracking.addTrackedItems([{ phrase: "AI agents", type: "keyword", platform: "twitter" }])
CLI:        xpoz-cli tracking add_tracked_items --items '[{"phrase": "AI agents", "type": "keyword", "platform": "twitter"}]'

Remove tracked items:

MCP:        call removeTrackedItems with items: [{ phrase: "AI agents", type: "keyword", platform: "twitter" }]
Python:     client.tracking.remove_tracked_items([...])
TypeScript: await client.tracking.removeTrackedItems([...])
CLI:        xpoz-cli tracking remove_tracked_items --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:

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.

MCP:        fields: ["id", "text", "authorUsername", "likeCount"]
Python:     fields=["id", "text", "author_username", "like_count"]
TypeScript: fields: ["id", "text", "authorUsername", "likeCount"]
CLI:        --fields id text author_username like_count

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

Detailed Guides

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

• [references/authentication.md](references/authentication.md) — Auth flows for MCP, SDK (API key), CLI
• [references/sdk.md](references/sdk.md) — Python & TypeScript SDK: setup, namespaces, pagination helpers, async patterns
• [references/cli.md](references/cli.md) — CLI installation, command structure, rendering modes, examples
• [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

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?"
• "How do I authenticate with the Xpoz Python SDK?"
• "Show me all available TikTok tools"