Search and export Twitter/X data to CSV files for analysis. Supports keyword search, author-based search, date filtering, and bulk exports up to 500K rows — no Twitter API keys required.
\nActivate when the user asks:
\nBefore fetching data, ensure Xpoz access is configured. Follow these checks in order.
\nIf you have MCP tools, try calling any Xpoz tool (e.g., checkAccessKeyStatus). If it works → skip to Step 1.
If you have the SDK, try:
\nfrom xpoz import XpozClient\nclient = XpozClient() # reads XPOZ_API_KEY env var\nIf this succeeds without error → skip to Step 1.
\nIf neither works, you need to authenticate. Get a free access key (below).
\nReal analyses need a real key: get a free access key (free tier, up to 75K results, no credit card). SDK and CLI users set it as XPOZ_API_KEY; MCP connections sign in with the same account via OAuth on first tool call (paths below).
If mcporter is available:
mcporter call xpoz.checkAccessKeyStatus\nIf hasAccessKey: true → ready. If not:
mcporter config add xpoz https://mcp.xpoz.ai/mcp --auth oauth\nThen authenticate — generate the OAuth URL and send it to the user:
\nStep 1: Generate authorization URL
\nimport secrets, hashlib, base64, urllib.parse, json, urllib.request, os\n\nverifier = secrets.token_urlsafe(64)\nchallenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest()).rstrip(b'=').decode()\nstate = secrets.token_urlsafe(32)\n\n# Dynamic client registration\nreg_req = urllib.request.Request(\n 'https://mcp.xpoz.ai/oauth/register',\n data=json.dumps({\n 'client_name': 'Agent Skills',\n 'redirect_uris': ['https://www.xpoz.ai/oauth/openclaw'],\n 'grant_types': ['authorization_code'],\n 'response_types': ['code'],\n 'token_endpoint_auth_method': 'none',\n }).encode(),\n headers={'Content-Type': 'application/json'},\n)\nreg_resp = json.loads(urllib.request.urlopen(reg_req).read())\n\nparams = urllib.parse.urlencode({\n 'response_type': 'code',\n 'client_id': reg_resp['client_id'],\n 'code_challenge': challenge,\n 'code_challenge_method': 'S256',\n 'redirect_uri': 'https://www.xpoz.ai/oauth/openclaw',\n 'state': state,\n 'scope': 'mcp:tools',\n 'resource': 'https://mcp.xpoz.ai/',\n})\n\nauth_url = 'https://mcp.xpoz.ai/oauth/authorize?' + params\n\n# Save state for token exchange\nos.makedirs(os.path.expanduser('~/.cache/xpoz-oauth'), exist_ok=True)\nwith open(os.path.expanduser('~/.cache/xpoz-oauth/state.json'), 'w') as f:\n json.dump({'verifier': verifier, 'state': state, 'client_id': reg_resp['client_id'],\n 'redirect_uri': 'https://www.xpoz.ai/oauth/openclaw'}, f)\n\nprint(auth_url)\nStep 2: Send the URL to the user
\nTell them:
\n\n\n\"I need to connect to Xpoz for social media data. Please open this link and sign in:
\n[auth_url]
\nAfter authorizing, you'll see a code. Paste it back to me here.\"
\n
Step 3: WAIT for the user to reply with the code. Do not proceed until they respond.
\nStep 4: Exchange the code for a token
\nOnce the user provides the code (either a raw code or a URL containing ?code=...), extract the code and exchange it:
import json, urllib.request, urllib.parse, subprocess, os\n\nwith open(os.path.expanduser('~/.cache/xpoz-oauth/state.json')) as f:\n oauth = json.load(f)\n\ncode = \"THE_CODE_FROM_USER\" # Extract from user's reply\n\ndata = urllib.parse.urlencode({\n 'grant_type': 'authorization_code',\n 'code': code,\n 'redirect_uri': oauth['redirect_uri'],\n 'client_id': oauth['client_id'],\n 'code_verifier': oauth['verifier'],\n}).encode()\n\nreq = urllib.request.Request(\n 'https://mcp.xpoz.ai/oauth/token',\n data=data,\n headers={'Content-Type': 'application/x-www-form-urlencoded'},\n)\nresp = json.loads(urllib.request.urlopen(req).read())\ntoken = resp['access_token']\n\n# Configure mcporter with the token (token is never printed)\nsubprocess.run(['mcporter', 'config', 'remove', 'xpoz'], capture_output=True)\nsubprocess.run(['mcporter', 'config', 'add', 'xpoz', 'https://mcp.xpoz.ai/mcp',\n '--header', f'Authorization=Bearer {token}'], check=True)\n\n# Clean up\nos.remove(os.path.expanduser('~/.cache/xpoz-oauth/state.json'))\nprint(\"Xpoz configured successfully\")\nStep 5: Verify with mcporter call xpoz.checkAccessKeyStatus → should return hasAccessKey: true.
For Claude Code users without mcporter:
\nclaude mcp add --transport http xpoz https://mcp.xpoz.ai/mcp\nClaude Code handles OAuth automatically on first tool call — the user just needs to authorize in their browser when prompted.
\nAsk the user:
\n\n\n\"I need a Xpoz API key to access social media data. Please go to https://xpoz.ai/get-token (it's free, no credit card needed) and paste the key back to me.\"
\n
WAIT for the user to reply with the key. Then:
\nPython:
\npip install xpoz\nfrom xpoz import XpozClient\nclient = XpozClient(\"THE_KEY_FROM_USER\")\nTypeScript:
\nnpm install @xpoz/xpoz\nimport { XpozClient } from \"@xpoz/xpoz\";\nconst client = new XpozClient({ apiKey: \"THE_KEY_FROM_USER\" });\nawait client.connect();\nOr set the environment variable and use the default constructor:
\nexport XPOZ_API_KEY=THE_KEY_FROM_USER\n| Problem | \nSolution | \n
|---|---|
| MCP: \"Unauthorized\" | \nRe-run the OAuth flow above | \n
SDK: AuthenticationError | \nVerify key at xpoz.ai/settings | \n
| Token exchange fails | \nAsk user to re-authorize — codes are single-use | \n
Extract:
\nBuild the query using boolean operators:
\n\"machine learning\"\"AI\" OR \"artificial intelligence\"\"Tesla\" AND \"earnings\"\"crypto\" NOT \"scam\"(\"deep learning\" OR \"neural network\") AND pythonSearch by keywords:
\nCall getTwitterPostsByKeywords:\n query: \"<query>\"\n fields: [\"id\", \"text\", \"authorUsername\", \"authorId\", \"createdAtDate\", \"likeCount\", \"retweetCount\", \"quoteCount\", \"impressionCount\", \"language\"]\n startDate: \"<YYYY-MM-DD>\"\n endDate: \"<YYYY-MM-DD>\"\n language: \"en\" (optional)\nSearch by author:
\nCall getTwitterPostsByAuthor:\n identifier: \"<username>\"\n identifierType: \"username\"\n fields: [\"id\", \"text\", \"createdAtDate\", \"likeCount\", \"retweetCount\", \"quoteCount\", \"impressionCount\"]\n startDate: \"<YYYY-MM-DD>\"\n endDate: \"<YYYY-MM-DD>\"\nCRITICAL: Async Pattern — calls return an operationId. Call checkOperationStatus with that ID and poll until \"completed\" (up to 8 retries, ~5 seconds apart).
CSV Export (two options):
\nresponseType=\"csv\" in the original call to get a CSV download directlydataDumpExportOperationId from the response — call checkOperationStatus with it to get an S3 download URL for the complete datasetfrom xpoz import XpozClient\n\nclient = XpozClient() # Uses XPOZ_API_KEY env var\n\n# Search by keywords\nresults = client.twitter.search_posts(\n '\"artificial intelligence\" AND ethics',\n start_date=\"2026-01-01\",\n end_date=\"2026-02-23\",\n language=\"en\",\n fields=[\"id\", \"text\", \"author_username\", \"created_at_date\", \"like_count\", \"retweet_count\", \"impression_count\"]\n)\n\nprint(f\"Found {results.pagination.total_rows:,} tweets\")\n\n# Export entire result set to CSV (up to 500K rows)\ncsv_url = results.export_csv()\nprint(f\"Download CSV: {csv_url}\")\n\n# Or search by author\nauthor_results = client.twitter.get_posts_by_author(\n \"elonmusk\",\n start_date=\"2026-01-01\",\n fields=[\"id\", \"text\", \"created_at_date\", \"like_count\", \"retweet_count\"]\n)\nauthor_csv = author_results.export_csv()\n\nclient.close()\nDownload and analyze locally:
\nimport pandas as pd\nimport subprocess\n\n# Download the CSV\nsubprocess.run([\"curl\", \"-L\", \"-o\", \"tweets.csv\", csv_url])\n\n# Load and analyze\ndf = pd.read_csv(\"tweets.csv\")\nprint(f\"Total tweets: {len(df)}\")\nprint(f\"Date range: {df['created_at_date'].min()} to {df['created_at_date'].max()}\")\nprint(f\"Average likes: {df['like_count'].mean():.1f}\")\nprint(f\"Top authors:\\n{df['author_username'].value_counts().head(10)}\")\nimport { XpozClient } from \"@xpoz/xpoz\";\n\nconst client = new XpozClient();\nawait client.connect();\n\nconst results = await client.twitter.searchPosts('\"artificial intelligence\" AND ethics', {\n startDate: \"2026-01-01\",\n endDate: \"2026-02-23\",\n language: \"en\",\n fields: [\"id\", \"text\", \"authorUsername\", \"createdAtDate\", \"likeCount\", \"retweetCount\"],\n});\n\nconsole.log(`Found ${results.pagination.totalRows.toLocaleString()} tweets`);\n\n// Export to CSV\nconst csvUrl = await results.exportCsv();\nconsole.log(`Download: ${csvUrl}`);\n\nawait client.close();\nAfter export, provide the user with:
\nexport_csv() / exportCsv())## Export Complete: [QUERY]\n\n**Rows exported:** 12,456\n**Period:** Jan 1 – Feb 23, 2026\n**Download:** [CSV link]\n\n### Sample Data\n| Date | Author | Text (truncated) | Likes | RTs |\n|------|--------|-------------------|-------|-----|\n| ... | ... | ... | ... | ... |\n\n### Quick Stats\n- Avg likes per tweet: 45.2\n- Most active author: @user (234 tweets)\n- Peak day: Feb 14, 2026 (1,203 tweets)\n\n### Suggested Next Steps\n- Load into pandas/Excel for deeper analysis\n- Filter by engagement (like_count > 100) for high-impact posts\n- Group by date for trend analysis\n| Field | \nDescription | \n
|---|---|
id | \nTweet ID | \n
text | \nFull tweet text | \n
authorUsername | \nAuthor's username | \n
authorId | \nAuthor's numeric ID | \n
createdAtDate | \nPost date (YYYY-MM-DD) | \n
likeCount | \nNumber of likes | \n
retweetCount | \nNumber of retweets | \n
quoteCount | \nNumber of quote tweets | \n
impressionCount | \nNumber of impressions | \n
replyCount | \nNumber of replies | \n
language | \nDetected language | \n
isRetweet | \nWhether it's a retweet | \n
isReply | \nWhether it's a reply | \n