Python SDK Quickstart

Installation

pip install xpoz

Requires Python 3.10+.

Get an Access Key

Start instantly — no account needed. Generate a free token and use it as your API key:

curl -s -X POST https://api.xpoz.ai/api/trial/token \
  -H "Content-Type: application/json" \
  -d '{"source": "docs"}' | jq -r .data.accessKey
# -> TRIAL...  (valid 5 days, all read tools across 4 platforms)

This returns a preview of up to 5 results per call. To get full data, pagination, and CSV export, create a free account — no credit card required.

Create a Client

The Python SDK provides both synchronous and asynchronous clients.

Sync
Async

from xpoz import XpozClient

# Pass access key directly
client = XpozClient("your-api-key")

# Or use the XPOZ_API_KEY environment variable
client = XpozClient()

from xpoz import AsyncXpozClient

client = AsyncXpozClient("your-api-key")
await client.connect()

Configuration Options

Parameter	Type	Default	Description
`api_key`	`str`	`os.environ["XPOZ_API_KEY"]`	Access key for authentication
`server_url`	`str`	`https://mcp.xpoz.ai/mcp`	MCP server URL
`timeout`	`int`	`300`	Operation timeout in seconds

client = XpozClient(
    "your-api-key",
    server_url="https://mcp.xpoz.ai/mcp",
    timeout=600,  # 10 minutes
)

Your First Call

Sync
Async

from xpoz import XpozClient

client = XpozClient("your-api-key")

# Get a Twitter user profile
user = client.twitter.get_user("elonmusk")
print(f"{user.name} — {user.followers_count:,} followers")

# Search for posts
results = client.twitter.search_posts("artificial intelligence", start_date="2025-01-01")
for tweet in results.data:
    print(tweet.text, tweet.like_count)

client.close()

import asyncio
from xpoz import AsyncXpozClient

async def main():
    async with AsyncXpozClient("your-api-key") as client:
        # Get a Twitter user profile
        user = await client.twitter.get_user("elonmusk")
        print(f"{user.name} — {user.followers_count:,} followers")

        # Search for posts
        results = await client.twitter.search_posts(
            "artificial intelligence", start_date="2025-01-01"
        )
        for tweet in results.data:
            print(tweet.text, tweet.like_count)

asyncio.run(main())

Context Managers

Use context managers to automatically close the client when done.

Sync
Async

with XpozClient("your-api-key") as client:
    user = client.twitter.get_user("elonmusk")
    # client.close() is called automatically

async with AsyncXpozClient("your-api-key") as client:
    user = await client.twitter.get_user("elonmusk")
    results = await client.twitter.search_posts("AI")
    page2 = await results.next_page()
    # client is closed automatically

Field Selection

All methods accept a fields parameter. Use snake_case field names — the SDK automatically converts to camelCase for the API.

results = client.twitter.search_posts(
    "AI",
    fields=["id", "text", "like_count", "retweet_count", "created_at_date"],
)

user = client.twitter.get_user(
    "elonmusk",
    fields=["id", "username", "name", "followers_count", "description"],
)

Requesting fewer fields significantly improves response time and reduces memory usage, especially for large result sets.

Query Syntax

The query parameter on search_posts, get_users_by_keywords, and similar methods supports Lucene-style full-text search:

# Exact phrase
client.twitter.search_posts('"machine learning"')

# Boolean operators
client.twitter.search_posts('"deep learning" AND python')
client.twitter.search_posts("tensorflow OR pytorch")
client.twitter.search_posts("climate AND policy")

# Grouping
client.twitter.search_posts('(AI OR "artificial intelligence") AND ethics')

# Combined with filters
results = client.twitter.search_posts(
    '("machine learning" OR "deep learning") AND python',
    start_date="2025-01-01",
    language="en",
)

Do not use from:, lang:, since:, or until: in the query string. Use the dedicated parameters (author_username, language, start_date, end_date) instead.

Environment Variables

Variable	Description	Default
`XPOZ_API_KEY`	Access key for authentication	—
`XPOZ_SERVER_URL`	MCP server URL	`https://mcp.xpoz.ai/mcp`

Next Steps

Pagination — navigate large result sets and export CSV
Error Handling — handle errors gracefully
SDK Reference — full list of methods and type models
TypeScript SDK Quickstart — equivalent guide for the TypeScript SDK

​Installation

​Get an Access Key

​Create a Client

​Configuration Options

​Your First Call

​Context Managers

​Field Selection

​Query Syntax

​Environment Variables

​Next Steps

Installation

Get an Access Key

Create a Client

Configuration Options

Your First Call

Context Managers

Field Selection

Query Syntax

Environment Variables

Next Steps