agentleFS
XPOZpublicXPOZpublic/xpoz-agent-skills/skills/xpoz-best-practices/SKILL.md

xpoz-best-practices

Skill15 starsChanged 2 months agoMITView on GitHub

Reference guide for using Xpoz effectively. Load this skill whenever working with Xpoz MCP tools, SDKs, or CLI — 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.

  • Reads credentials
  • Installs packages

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 3 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    All keyword search tools support boolean query syntax:

    line 79
  2. Very specific:

    Date filtering: Use startDate / endDate in YYYY-MM-DD format.

    line 88
  3. Very specific:

    All paginated tools support three response modes via responseType:

    line 205
  4. Distinctive:

    Search posts by keywords (fast mode) to preview results

    line 231
  5. Distinctive:

    Search users by keywords to find relevant accounts

    line 236
  6. Very specific:

    Use forceLatest: true to bypass cache and force a live fetch (increases latency and cost)

    line 242

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 for detailed auth flows (MCP, SDK, CLI). See references/sdk.md for complete Python & TypeScript SDK reference. See references/cli.md for CLI installation, commands, and rendering modes.

Query Syntax

All keyword search tools support boolean query syntax:

OperatorExampleEffect
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 pythonCombines 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)

ToolPurpose
getTwitterUser / getTwitterUsersLook up 1-100 users by ID or username
searchTwitterUsersFuzzy search users by name
getTwitterUserConnectionsGet followers or following
getTwitterUsersByKeywordsFind users who posted about a topic
getTwitterPostsByIdsGet 1-100 posts by ID
getTwitterPostsByAuthorGet all posts from a username
getTwitterPostsByKeywordsSearch posts by keywords
getTwitterPostRetweetsGet retweets of a post
getTwitterPostQuotesGet quote tweets of a post
getTwitterPostCommentsGet replies to a post
getTwitterPostInteractingUsersGet commenters, quoters, or retweeters
countTweetsCount tweets matching a phrase

See references/twitter.md for all parameters, fields, and examples.

Instagram (9 tools)

ToolPurpose
getInstagramUserLook up user by ID or username
searchInstagramUsersFuzzy search users by name
getInstagramUserConnectionsGet followers or following
getInstagramUsersByKeywordsFind users who posted about a topic
getInstagramPostInteractingUsersGet commenters or likers of a post
getInstagramPostsByIdsGet posts by strong_id
getInstagramPostsByUserGet posts from a user
getInstagramPostsByKeywordsSearch posts by keywords in captions/subtitles
getInstagramCommentsByPostIdGet comments on a post

See references/instagram.md for all parameters, fields, and examples.

Reddit (9 tools)

ToolPurpose
getRedditUserLook up user by username
searchRedditUsersFuzzy search users by name
getRedditUsersByKeywordsFind users who posted about a topic
getRedditPostsByKeywordsSearch posts by keywords
getRedditPostWithCommentsByIdGet a post with all its comments
getRedditCommentsByKeywordsSearch comments by keywords
searchRedditSubredditsSearch subreddits by name
getRedditSubredditWithPostsByNameGet subreddit details with posts
getRedditSubredditsByKeywordsSearch subreddits by keyword in description

See references/reddit.md for all parameters, fields, and examples.

TikTok (9 tools)

ToolPurpose
getTiktokUserLook up user by ID or username
searchTiktokUsersFuzzy search users by name
getTiktokUsersByKeywordsFind users who posted about a topic
getTiktokUsersByHashtagsFind users who used specific hashtags
getTiktokPostsByIdsGet posts by ID
getTiktokPostsByUserGet posts from a user
getTiktokPostsByKeywordsSearch posts by keywords
getTiktokPostsByHashtagsSearch posts by hashtags
getTiktokCommentsByPostIdGet comments on a post

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

Platformkeywordusersubreddithashtag
TwitterYesYes——
InstagramYesYes——
RedditYesYesYes—
TikTokYesYes—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 for full tracking workflows and advanced patterns.

Response Modes

All paginated tools support three response modes via responseType:

ModeBehaviorBest For
"fast" (default)Returns up to 300 results immediatelyQuick lookups, exploration
"paging"Async — returns operationId, poll with checkOperationStatusLarge datasets, page-by-page
"csv"Async CSV export to S3 — returns download URLBulk export, offline analysis

See 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

ProblemSolution
MCP: "Unauthorized"Re-run OAuth flow — see references/authentication.md
SDK: AuthenticationErrorVerify key at xpoz.ai/settings
Empty resultsCheck query syntax, widen date range, try different keywords
Stale dataUse forceLatest: true to bypass cache
Operation timeoutKeep polling checkOperationStatus every ~5s until status is no longer running
Token exchange failsAsk user to re-authorize — codes are single-use

Detailed Guides

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

  • references/authentication.md — Auth flows for MCP, SDK (API key), CLI
  • references/sdk.md — Python & TypeScript SDK: setup, namespaces, pagination helpers, async patterns
  • references/cli.md — CLI installation, command structure, rendering modes, examples
  • references/pagination-and-export.md — Response modes, operationId polling, CSV export, field selection
  • references/twitter.md — All 13 Twitter tools with parameters, fields, and examples
  • references/instagram.md — All 9 Instagram tools with parameters, fields, and examples
  • references/reddit.md — All 9 Reddit tools with parameters, fields, and examples
  • 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"

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.