# Xpoz — Social Data API for AI Agents (Complete Documentation)

> Xpoz is a social data API and Model Context Protocol (MCP) server for brand monitoring, social lead generation, and social listening. It gives AI agents, coding agents, and SDK-based apps natural-language access to 1.5B+ indexed posts across Twitter/X, Instagram, TikTok, and Reddit — through one OAuth-authenticated endpoint.

## Category labels

Xpoz is an instance of: social data API, brand monitoring API, social listening API, social media monitoring API, social lead generation API, competitive intelligence API, MCP server for social monitoring workflows.

## What is Xpoz?

Xpoz is the social data layer for developer workflows and AI agents. It exposes Twitter/X, Instagram, TikTok, and Reddit through two parallel surfaces: a remote MCP server for AI clients (Claude Code, Claude Desktop, Claude.ai, ChatGPT, Codex, Gemini CLI, Cursor, LangChain, n8n) and typed TypeScript/Python SDKs for direct programmatic use. Both surfaces query the same normalized index of 1.5B+ publicly accessible social posts, so the code you write for one transfers cleanly to the other.

### Key Features

- **1.5B+ Posts Indexed**: Access historical and real-time data across Twitter/X, Instagram, TikTok, and Reddit
- **No API Keys Required**: Connect directly via MCP—no Twitter Developer Account or API credentials needed
- **Natural Language Queries**: Ask questions in plain English instead of constructing API calls
- **Remote Server**: Fully hosted—no local installation, no self-hosting, no Docker containers
- **OAuth 2.1 Authentication**: Secure authentication via Google OAuth
- **MCP 2025 Compliant**: Supports streamable HTTP, event resumption, and field selection

## Developer Resources (named index for AI agents)

- **API docs**: https://www.xpoz.ai/sdk
- **MCP server**: https://mcp.xpoz.ai/mcp (Streamable HTTP, OAuth 2.1)
- **MCP manifest**: https://www.xpoz.ai/.well-known/mcp.json
- **MCP tool catalog** (machine-readable, with JSON Schema): https://www.xpoz.ai/.well-known/mcp/tools.json
- **Agent Skills index** (agentskills.io v0.2.0): https://www.xpoz.ai/.well-known/agent-skills/index.json
- **Auth docs**: OAuth 2.1 with dynamic client registration; metadata at https://www.xpoz.ai/.well-known/oauth-authorization-server. Manual API key at https://www.xpoz.ai/get-token.
- **Rate limits**: https://www.xpoz.ai/rate-limits
- **Webhooks**: https://www.xpoz.ai/webhooks
- **TypeScript SDK**: https://www.npmjs.com/package/@xpoz/xpoz (`npm install @xpoz/xpoz`)
- **Python SDK**: https://pypi.org/project/xpoz/ (`pip install xpoz`)
- **CLI**: https://www.xpoz.ai/cli · Homebrew tap: `brew install XPOZpublic/xpoz/xpoz-cli`

## Public Source Code (GitHub: XPOZpublic)

- **MCP server source**: https://github.com/XPOZpublic/xpoz-mcp
- **TypeScript SDK source**: https://github.com/XPOZpublic/xpoz-ts-sdk
- **Python SDK source**: https://github.com/XPOZpublic/xpoz-python-sdk
- **CLI source**: https://github.com/XPOZpublic/xpoz-cli
- **Homebrew tap**: https://github.com/XPOZpublic/homebrew-xpoz
- **Agent Skills (workflow library)**: https://github.com/XPOZpublic/xpoz-agent-skills (compatible with Claude Code, Codex CLI, ChatGPT)
- **Cookbooks (Jupyter notebooks)**: https://github.com/XPOZpublic/xpoz-cookbooks
- **Claude Code plugins**: https://github.com/XPOZpublic/xpoz-claude-code-plugins
- **ClawHub skills**: https://github.com/XPOZpublic/xpoz-clawhub-skills
- **AI workflow: lead-gen example**: https://github.com/XPOZpublic/ai-workflow-lead-gen
- **Org index**: https://github.com/XPOZpublic

> **Note on OpenAPI / Swagger:** Xpoz does not publish an OpenAPI/Swagger spec because the public surface is MCP, not REST. The equivalent machine-readable contract is the MCP manifest plus the tool catalog above. Each tool's `inputSchema` is JSON Schema and is directly usable by any function-calling LLM.

## MCP Server Connection Details

**Server URL:** `https://mcp.xpoz.ai/mcp`
**Transport:** Streamable HTTP (MCP 2025 specification)
**Authentication:** OAuth 2.1 via Google

### For Claude.ai Web or Claude Desktop

1. Go to Settings → Connectors
2. Click "Add custom connector"
3. Enter URL: `https://mcp.xpoz.ai/mcp`
4. Complete OAuth authentication when prompted

### For Claude Code CLI

```bash
claude mcp add --transport http --scope user xpoz-mcp https://mcp.xpoz.ai/mcp --header "Authorization: Bearer [your-api-token]"
```

Replace `[your-api-token]` with your Xpoz API key from the settings dashboard.

### For ChatGPT and Other MCP Clients

Use the remote MCP server URL: `https://mcp.xpoz.ai/mcp`
Configure your MCP client to connect via streamable HTTP transport.

---

## Claude Skills (Pre-built Workflows)

Xpoz provides pre-built Claude Code skills for common brand intelligence tasks:

### Brand Snapshot
**Command:** `/brand-snapshot [BRAND]`
**URL:** https://www.xpoz.ai/apps/claude-skills/brand-snapshot/

Analyze any brand's social presence with a single command. Get sentiment analysis, key narratives, top influencers, and a SWOT analysis powered by real-time social data.

Features:
- Multi-platform sentiment analysis across Twitter, Reddit, and Instagram
- Narrative extraction identifying key themes and talking points
- Influencer identification with engagement metrics
- Automated SWOT analysis based on social signals
- Real-time data from the last 7 days

### Brand Competition
**Command:** `/brand-competition [YOUR_BRAND] vs [COMPETITOR]`
**URL:** https://www.xpoz.ai/apps/claude-skills/brand-competition/

Compare your brand against competitors with share of voice analysis, sentiment comparison, and competitive positioning insights.

Features:
- Share of voice comparison across platforms
- Sentiment comparison between brands
- Topic overlap and differentiation analysis
- Competitor audience insights
- Engagement rate benchmarking

### Brand Influencers
**Command:** `/brand-influencers [BRAND]`
**URL:** https://www.xpoz.ai/apps/claude-skills/brand-influencers/

Find the perfect influencers for your brand with AI-powered discovery. Classify by tier (Mega/Macro/Micro/Nano), analyze sentiment, and identify partnership potential.

Features:
- Influencer tier classification (Mega/Macro/Micro/Nano)
- Voice type analysis (advocates, critics, neutral)
- Engagement rate and reach metrics
- Sentiment analysis of influencer content
- Partnership potential scoring

**Source Code:** https://github.com/XPOZpublic/xpoz-claude-code-plugins

---

## Complete Tool Reference

### Twitter/X Tools

#### `getTwitterPostsByKeywords`
Search tweets by keywords with powerful boolean operators.

**Parameters:**
- `query` (required): Search query. Use double quotes for exact phrases ("climate change"), AND/OR operators for boolean logic
- `startDate` (optional): Start date filter (YYYY-MM-DD)
- `endDate` (optional): End date filter (YYYY-MM-DD)
- `language` (optional): Filter by language code (en, es, etc.)
- `authorUsername` (optional): Filter by author username
- `fields` (optional): Specify fields to return. Default: ["id", "text", "authorUsername", "createdAtDate"]

**Available Fields:**
- Core: id, text, authorId, authorUsername, createdAt, createdAtDate
- Engagement: retweetCount, replyCount, likeCount, quoteCount, impressionCount, bookmarkCount
- Content: hashtags, mentions, mediaUrls
- Location: country, region, city
- Metadata: lang, source, conversationId

**Example Queries:**
- `"artificial intelligence" AND ethics` - Exact phrase with keyword
- `(startup OR entrepreneur) NOT "venture capital"` - Boolean with exclusion
- `#AI OR #MachineLearning` - Hashtag search

**Returns:** Paginated results with dataDumpExportOperationId for CSV export

---

#### `getTwitterPostsByAuthor`
Get all posts from a specific Twitter user.

**Parameters:**
- `identifier` (required): Username or numeric user ID
- `identifierType` (required): "username" or "id"
- `startDate` (optional): Start date filter
- `endDate` (optional): End date filter
- `fields` (optional): Fields to return

**Example:** Get @elonmusk's tweets from the last month with engagement metrics

---

#### `getTwitterUser`
Get detailed user profile information.

**Parameters:**
- `identifier` (required): Username or numeric user ID
- `identifierType` (required): "username" or "id"
- `fields` (optional): Default: ["id", "username", "name"]

**Available Fields:**
- Core: id, username, name, description, location, verified, verifiedType
- Engagement: followersCount, followingCount, tweetCount, listedCount, likesCount
- Profile: profileImageUrl, profileBannerUrl
- Advanced: isInauthentic, isInauthenticProbScore (bot detection)

---

#### `getTwitterUserConnections`
Get followers or following list for any user.

**Parameters:**
- `username` (required): Twitter username (without @)
- `connectionType` (required): "followers" or "following"
- `fields` (optional): User fields to return
- `forceLatest` (optional): Bypass cache for real-time data

**Returns:** Paginated list with totalDataCount showing actual Twitter total

---

#### `getTwitterUsersByKeywords`
Find users who have posted about specific topics.

**Parameters:**
- `query` (required): Search query (searches tweet content)
- `startDate`/`endDate` (optional): Date filters
- `fields` (optional): Include aggregate fields like relevantTweetsCount, relevantTweetsLikesSum

**Use Case:** Find influencers or experts who discuss specific topics

---

#### `getTwitterPostComments`
Get replies to a specific tweet.

**Parameters:**
- `postId` (required): Tweet ID
- `startDate` (optional): Filter replies from date
- `fields` (optional): Fields to return

---

#### `getTwitterPostQuotes`
Get quote tweets of a specific post.

**Parameters:**
- `postId` (required): Tweet ID
- `startDate` (optional): Filter quotes from date
- `fields` (optional): Fields to return

---

#### `getTwitterPostRetweets`
Get retweets of a specific post (database-only search).

**Parameters:**
- `postId` (required): Tweet ID
- `fields` (optional): Fields to return

---

#### `getTwitterPostInteractingUsers`
Get users who interacted with a post.

**Parameters:**
- `postId` (required): Tweet ID
- `interactionType` (required): "commenters", "quoters", or "retweeters"
- `fields` (optional): User fields to return

---

#### `searchTwitterUsers`
Search for Twitter users by name (real-time API search).

**Parameters:**
- `name` (required): Search query
- `limit` (optional): Max results (default 10)
- `fields` (optional): Fields to return

---

#### `countTweets`
Count tweets matching a phrase within a date range.

**Parameters:**
- `phrase` (required): Search phrase (use quotes for exact match)
- `startDate` (optional): Start date (default: 6 months ago)
- `endDate` (optional): End date (default: today)

**Use Case:** Trend analysis, measuring topic volume over time

---

### Instagram Tools

#### `getInstagramPostsByKeywords`
Search Instagram posts by keywords in captions and video subtitles.

**Parameters:**
- `query` (required): Search query with boolean operators
- `startDate`/`endDate` (optional): Date filters
- `fields` (optional): Default: ["id", "caption", "username", "createdAtDate"]

**Available Fields:**
- Core: id, postType, userId, username, caption, createdAtDate
- Engagement: likeCount, commentCount, reshareCount, videoPlayCount
- Media: mediaType, imageUrl, videoUrl, subtitles

---

#### `getInstagramPostsByUser`
Get all posts from an Instagram user.

**Parameters:**
- `identifier` (required): Username or user ID
- `identifierType` (required): "username" or "id"
- `startDate`/`endDate` (optional): Date filters
- `fields` (optional): Fields to return

---

#### `getInstagramUser`
Get Instagram user profile.

**Parameters:**
- `identifier` (required): Username or user ID
- `identifierType` (required): "username" or "id"
- `fields` (optional): Default: ["id", "username", "fullName"]

**Available Fields:**
- Core: id, username, fullName, biography, isPrivate, isVerified
- Engagement: followerCount, followingCount, mediaCount
- Profile: profilePicUrl, externalUrl

---

#### `getInstagramUserConnections`
Get Instagram followers or following list.

**Parameters:**
- `username` (required): Instagram username
- `connectionType` (required): "followers" or "following"
- `fields` (optional): User fields to return

---

#### `getInstagramCommentsByPostId`
Get comments on an Instagram post.

**Parameters:**
- `postId` (required): Post ID in strong_id format (e.g., "3606450040306139062_4836333238")
- `fields` (optional): Default: ["id", "text", "username", "createdAtDate"]

**Important:** Use the full "id" value from other Instagram tools, not just the media_id.

---

#### `getInstagramPostInteractingUsers`
Get user profiles of people who interacted with a post.

**Parameters:**
- `postId` (required): Post ID in strong_id format
- `interactionType` (required): "commenters" or "likers"
- `fields` (optional): User profile fields

---

### Reddit Tools

#### `getRedditPostsByKeywords`
Search Reddit posts by keywords in titles and content.

**Parameters:**
- `query` (required): Search query with boolean operators
- `subreddit` (optional): Limit to specific subreddit (without r/)
- `sort` (optional): relevance, hot, top, new, comments
- `time` (optional): hour, day, week, month, year, all
- `startDate`/`endDate` (optional): Date filters
- `fields` (optional): Default: ["id", "title", "authorUsername", "subredditName", "createdAtDate"]

**Available Fields:**
- Core: id, title, selftext, url, permalink
- Engagement: score, upvotes, downvotes, upvoteRatio, commentsCount
- Meta: subredditName, authorUsername, isOriginalContent, over18

---

#### `getRedditCommentsByKeywords`
Search Reddit comments by keywords.

**Parameters:**
- `query` (required): Search query
- `subreddit` (optional): Limit to specific subreddit
- `startDate`/`endDate` (optional): Date filters
- `fields` (optional): Comment fields

---

#### `getRedditPostWithCommentsById`
Get a Reddit post with all its comments.

**Parameters:**
- `postId` (required): Reddit post ID
- `postFields` (optional): Fields for the post
- `commentFields` (optional): Fields for comments

**Returns:** Post data on first page, paginated comments with CSV export

---

#### `getRedditSubredditWithPostsByName`
Get subreddit information and posts.

**Parameters:**
- `subredditName` (required): Subreddit name (without r/)
- `subredditFields` (optional): Subreddit info fields
- `postFields` (optional): Post fields

---

#### `getRedditUser`
Get Reddit user profile.

**Parameters:**
- `username` (required): Reddit username (without u/)
- `fields` (optional): Default: ["id", "username", "totalKarma"]

**Available Fields:**
- Core: id, username, profileUrl, profilePicUrl
- Karma: linkKarma, commentKarma, totalKarma
- Status: isGold, isMod, isEmployee, hasVerifiedEmail

---

### Utility Tools

#### `checkOperationStatus`
Check status and retrieve results from background operations.

**Parameters:**
- `operationId` (required): Operation ID returned by query tools

**Behavior:**
- Poll until status is "completed", "failed", or "cancelled"
- Wait 5 seconds between polls
- Returns paginated results and dataDumpExportOperationId for CSV export

---

## Pagination Pattern

All list queries use server-side pagination:

1. **First Call:** Omit pageNumber and tableName. Returns page 1 with:
   - `tableName`: Use for subsequent pages
   - `totalPages`: Total number of pages
   - `totalRows`: Total results in database
   - `dataDumpExportOperationId`: For CSV export

2. **Subsequent Pages:** Include `tableName` and `pageNumber`:
   ```
   tableName: "cached_table_abc123"
   pageNumber: 2
   ```

3. **Bulk Fetch:** Use `pageNumberEnd` to fetch multiple pages at once:
   ```
   pageNumber: 1
   pageNumberEnd: 5
   ```

---

## CSV Export

Every paginated query returns a `dataDumpExportOperationId`. Use this with `checkOperationStatus` to get a download URL for the complete dataset as CSV.

**Workflow:**
1. Run a search query
2. Get `dataDumpExportOperationId` from response
3. Call `checkOperationStatus` with that ID
4. Poll until complete (usually 30-60 seconds)
5. Download CSV from returned `downloadUrl`

---

## Query Syntax

### Exact Phrase Matching
Use double quotes: `"climate change"` matches that exact phrase

### Boolean Operators
- `AND`: Both terms required - `"machine learning" AND python`
- `OR`: Either term - `startup OR entrepreneur`
- `NOT`: Exclude term - `AI NOT "artificial intelligence"`
- Parentheses: Group logic - `(AI OR ML) AND ethics`

### Important
- Space between words defaults to OR
- Always use explicit AND/OR for precise queries
- Do NOT use colon operators (from:, since:, etc.) - use dedicated parameters

---

## Pricing Tiers

| Plan | Monthly Results | Tracked Items | Price |
|------|-----------------|---------------|-------|
| Free | 100,000 | 1 | $0 |
| Pro | 1,000,000 | 10 | $20/month |
| Max | 10,000,000 | 30 | $200/month |
| Enterprise | Unlimited | Unlimited | Custom |

**Overages:** Pro: $2.5/100k, Max: $1.5/100k

**Pricing Page:** https://www.xpoz.ai/pricing

---

## Use Cases by Industry

### Finance & Trading
- Detect market-moving tweets before the market reacts
- Track crypto sentiment and whale activity
- Monitor earnings call reactions
- **Page:** https://www.xpoz.ai/use-cases/finance/

### Security & OSINT
- Detect zero-day discussions before CVE drops
- Identify bot networks and coordinated campaigns
- Track threat actor activity
- **Page:** https://www.xpoz.ai/use-cases/security/

### Sales Development
- Find buyers showing purchase intent
- Identify companies ready to buy
- Monitor competitor customer complaints
- **Page:** https://www.xpoz.ai/use-cases/sales/

### Crisis Management
- Real-time brand monitoring across platforms
- Detect viral content before it explodes
- Track sentiment during PR events
- **Page:** https://www.xpoz.ai/use-cases/crisis-management/

### Developer Relations
- Understand developer community at scale
- Track SDK/API sentiment
- Identify developer advocates
- **Page:** https://www.xpoz.ai/use-cases/devrel/

---

## Frequently Asked Questions

### General

**Do I need a Twitter API key?**
No! That's the whole point. Xpoz provides direct access to social media data without requiring expensive API keys, avoiding rate limits and costs entirely.

**How do I get an access key?**
After installing, authenticate via OAuth through your Google account. The server guides you through the simple process on first use.

**What's the difference between Claude Desktop and Claude.ai?**
Both Claude Desktop and Claude.ai web use Web Connectors for remote MCP servers. The setup is the same: add a custom connector via Settings → Connectors with the remote server URL.

**Can I use this commercially?**
Yes! Xpoz MCP is available for both personal and commercial use. Check our licensing terms for specific details about your use case.

**What data is available?**
Access tweets, user profiles, Instagram posts, engagement metrics, hashtags, mentions, media URLs, and full historical data. See docs for complete field lists.

**What is MCP (Model Context Protocol)?**
MCP (Model Context Protocol) is an open standard developed by Anthropic that allows AI assistants like Claude to securely connect to external data sources and tools. Think of it as a universal adapter that lets AI models access real-world data without custom API integrations for each service.

**How does Xpoz compare to Twitter API?**
Unlike Twitter's official API which requires developer approval, rate limits, and costs $100-$5,000/month, Xpoz provides instant access through MCP with no API keys required. You get natural language queries instead of complex API calls, access to 1.5B+ posts, and pricing that starts free.

**What social media platforms does Xpoz support?**
Xpoz currently supports Twitter/X, Instagram, TikTok, and Reddit. You can search posts, profiles, hashtags, and trends across all platforms using natural language queries through Claude or other MCP-compatible AI assistants.

**Can I use Xpoz with ChatGPT?**
Yes! Xpoz works with both Claude and ChatGPT. For Claude, use the native MCP integration. For ChatGPT, connect via our remote MCP server URL in your ChatGPT settings. Both platforms support natural language queries to access social media data.

**How much does Twitter API cost vs Xpoz?**
Twitter's Basic API costs $100/month for 10,000 tweets. Their Pro tier is $5,000/month. Xpoz offers a free tier with 100,000 results/month, Pro at $20/month for 1M results, and Max at $200/month for 10M results—up to 100x more data for a fraction of the cost.

**What Reddit data can I access with Xpoz?**
With Xpoz, you can search Reddit posts and comments by subreddit, keywords, or users. Access post titles, content, upvotes, comments, and user information across any public subreddit—all through natural language queries with Claude.

### Pricing

**How are credits calculated?**
Credits are calculated using a simple formula: Credits = (Queries × 5) + (Results × 0.005). Each query costs 5 credits, and each result costs 0.005 credits (or 1 credit per 200 results). For example, 100 queries returning 100,000 total results would use 1,000 credits.

**What happens if I exceed my credit limit?**
Free tier users have a hard stop when credits run out—you'll need to upgrade to continue. Pro and Max users can continue using the service with overage charges: $0.80 per 1,000 credits for Pro, and $0.40 per 1,000 credits for Max. You can also upgrade to a higher tier at any time.

**Do Free tier credits refresh monthly?**
No, Free tier credits are a one-time allocation of 5,000 credits. Once used, you'll need to upgrade to Pro or Max to continue. This lets you thoroughly test the platform before committing to a paid plan.

**What are "tracked keywords" and "tracked users"?**
Tracked keywords allow you to set up continuous monitoring for specific terms, phrases, hashtags, or @mentions. Tracked users let you monitor specific social media accounts. Xpoz will automatically collect new posts matching your keywords or from your tracked users and make them available through the MCP tools. This is perfect for brand monitoring, competitive intelligence, influencer tracking, or following trending topics without manual queries. You can use any combination of keywords and users up to your plan limit.

**Can I change plans at any time?**
Yes! You can upgrade or downgrade your plan at any time from your dashboard. Upgrades take effect immediately and you'll be prorated for the remaining time in your billing cycle. Downgrades take effect at the start of your next billing period.

**What's included in "Premium Tools"?**
Premium tools include advanced analytics functions like sentiment analysis, influence scoring, network visualization, trend detection, and custom data exports. These tools are designed for power users who need deeper insights beyond basic data retrieval.

**Is there a trial period?**
The Free tier is available indefinitely, so you can explore Xpoz without any commitment. Paid plans (Pro and Max) come with a 14-day money-back guarantee. If you're not satisfied for any reason, contact us within 14 days for a full refund.

---

## Support

- **Help Center:** https://help.xpoz.ai
- **Email:** support@xpoz.ai
- **Twitter:** https://x.com/XPOZAI
- **LinkedIn:** https://linkedin.com/company/xpozinc
- **YouTube:** https://www.youtube.com/@xpoz-ai

---

## Links

- Website: https://www.xpoz.ai
- MCP Server: https://mcp.xpoz.ai/mcp
- Pricing: https://www.xpoz.ai/pricing
- Blog: https://www.xpoz.ai/blog
- GitHub: https://github.com/hossenco
- Claude Skills Source: https://github.com/XPOZpublic/xpoz-claude-code-plugins