xpoz-getting-started

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 returns hasAccessKey: true, skip to Step 4
• SDK: try importing XpozClient — if no error, skip to Step 4

Step 2: Set Up Authentication

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 xpoz

Ask 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_USER

TypeScript SDK

npm install @xpoz/xpoz

Ask 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_USER

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

Skill Routing

"I want to..."	Use this skill
Export tweets to CSV	twitter-data-export
Find influencers	influencer-discovery
Compare brands	competitive-intel
Analyze sentiment	social-sentiment-analyzer
Research Reddit discussions	reddit-research
Monitor security threats	security-osint
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 5

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?"