xpoz-getting-started
Skill15 starsChanged 2 months agoMITView on GitHub
Get started with Xpoz — set up authentication, verify your account, configure tracking, and discover available skills. 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".
- Reads credentials
- Installs packages
In this repository13 other files it gives its agents.
- ai-answer-traceSkill
- competitive-intelSkill
- creator-authenticity-scoreSkill
- geo-redditSkill
- geo-visibility-checkSkill
- influencer-discoverySkill
- lead-gen-scanSkill
- reddit-researchSkill
- security-osintSkill
- social-sentiment-analyzerSkill
- twitter-data-exportSkill
- xpoz-best-practicesSkill
- xpoz-social-trackingSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 3 are distinctive, and 2 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.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 45
Add the Xpoz MCP server to your agent's config.
- Distinctive: line 70
WAIT for the user to reply with the key: Do not proceed until they respond.
- Distinctive: line 88
Ask the user for the key (same URL).
- Distinctive: line 145
WAIT for the user to reply: Do not proceed until they respond.
- Very specific: line 165
Call getAccountDetails to check available tracked item slots.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 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.
Files
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. Available via MCP tools, Python SDK, TypeScript SDK, and CLI.
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: Choose Your Integration Path
| Situation | Path |
| Using an MCP-compatible AI agent (Claude Code, Cursor, Windsurf, etc.) | MCP |
| Building a Python application | Python SDK |
| Building a TypeScript/Node.js application | TypeScript SDK |
| Running from terminal | CLI |
Quick check — already set up?
- MCP: call
checkAccessKeyStatus— if it returnshasAccessKey: true, skip to Step 4 - SDK: try importing
XpozClient— if no error, skip to Step 4
Step 2: Set Up Authentication
Recommended: a free access key
Real results need a real key: get a free access key (free tier, up to 75K results, no credit card), then follow your integration path (MCP, SDK, or CLI, below). MCP connections sign in with the same account via OAuth on first tool call.
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"
}
}
}For other MCP clients, consult your agent's documentation for how to add an MCP server by URL.
Python SDK
pip install xpozAsk the user:
"Go to https://xpoz.ai/get-token (free, no credit card) and paste the key."
WAIT for the user to reply with the key. Do not proceed until they respond.
from xpoz import XpozClient
client = XpozClient("THE_KEY_FROM_USER")Or set the environment variable and use the default constructor:
export XPOZ_API_KEY=THE_KEY_FROM_USERTypeScript SDK
npm install @xpoz/xpozAsk the user for the key (same URL).
WAIT for the user to reply with the key. Do not proceed until they respond.
import { XpozClient } from "@xpoz/xpoz";
const client = new XpozClient({ apiKey: "THE_KEY_FROM_USER" });
await client.connect();CLI
pip install xpoz-cli
export XPOZ_API_KEY=THE_KEY_FROM_USERAuth Errors
| Problem | Solution |
| MCP: "Unauthorized" | Re-run the OAuth flow |
SDK: AuthenticationError | Verify key at xpoz.ai/settings |
| Token exchange fails | Ask user to re-authorize — codes are single-use |
See xpoz-best-practices/references/authentication.md for detailed auth flows and troubleshooting.
Step 3: Verify Your Setup
MCP: call checkAccessKeyStatus — expect hasAccessKey: true.
Then 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 |
| Yes | Yes | — | — | |
| Yes | Yes | — | — | |
| 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 for advanced tracking workflows.
Step 5: What Can You Do?
Platform Capabilities
| Platform | Users | Posts | Comments | Connections | Interactions | Special |
| lookup, search, by keywords | by ID, author, keywords | replies | followers/following | commenters/quoters/retweeters | countTweets | |
| lookup, search, by keywords | by ID, user, keywords | by post | followers/following | commenters/likers | strong_id format | |
| 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 |
Skill Routing
| "I want to..." | Use this skill |
| Export tweets to CSV | twitter-data-export |
| Find influencers | influencer-discovery |
| Vet Instagram creators | creator-authenticity-score |
| Compare brands | competitive-intel |
| Analyze sentiment | social-sentiment-analyzer |
| Research Reddit discussions | reddit-research |
| Monitor security threats | security-osint |
| See what AI engines cite | ai-answer-trace |
| Check my brand's AI visibility | geo-visibility-check |
| Get cited by AI via Reddit | geo-reddit |
| Find buying-intent leads | lead-gen-scan |
| Track keywords/users | xpoz-social-tracking |
| Learn Xpoz patterns | xpoz-best-practices |
Try It Now
Quick examples to try immediately:
MCP:
Call getTwitterPostsByKeywords:
query: "AI agents"
fields: ["id", "text", "authorUsername", "likeCount"]Python:
results = client.twitter.search_posts(
"AI agents",
fields=["id", "text", "author_username", "like_count"]
)
for post in results.data[:5]:
print(f"@{post.author_username}: {post.text[:100]}")TypeScript:
const results = await client.twitter.searchPosts("AI agents", {
fields: ["id", "text", "authorUsername", "likeCount"],
});
results.data.slice(0, 5).forEach(post =>
console.log(`@${post.authorUsername}: ${post.text.slice(0, 100)}`)
);CLI:
xpoz-cli twitter search_posts --query "AI agents" --fields id text author_username like_count --limit 5Example 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?"
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
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.

