Xpoz Best Practices

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:

| 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:

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:

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

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

| Problem | Solution | |---------|----------| | MCP: "Unauthorized" | Re-run OAuth flow — see [references/authentication.md](references/authentication.md) | | SDK: AuthenticationError | Verify key at xpoz.ai/settings | | 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 | | Token exchange fails | Ask user to re-authorize — codes are single-use |

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"

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: XPOZpublic
• Source: XPOZpublic/xpoz-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.