PaginatedResult
Methods that return large datasets use server-side pagination (100 items per page). These return a PaginatedResult[T] (sync) or AsyncPaginatedResult[T] (async) with built-in navigation helpers.
results = client.twitter.search_posts("AI")
# Access current page data
results.data # list[TwitterPost] — current page items
results.pagination.total_rows # total matching rows
results.pagination.total_pages # total pages
results.pagination.page_number # current page number
results.pagination.page_size # items per page (100)
results.pagination.results_count # items on current page
results.has_next_page() # bool
results = await client.twitter.search_posts("AI")
# Same attributes, but navigation methods are awaited
results.data # list[TwitterPost]
results.pagination.total_rows # total matching rows
results.has_next_page() # bool
Navigating Pages
results = client.twitter.search_posts("AI")
# Fetch the next page
if results.has_next_page():
page2 = results.next_page()
print(page2.data) # next 100 items
# Jump to a specific page
page5 = results.get_page(5)
results = await client.twitter.search_posts("AI")
# Fetch the next page
if results.has_next_page():
page2 = await results.next_page()
# Jump to a specific page
page5 = await results.get_page(5)
Exporting to CSV
Any paginated result can be exported to CSV. This triggers a server-side export and returns a download URL.
results = client.twitter.search_posts("AI")
csv_url = results.export_csv()
print(csv_url) # URL to download the CSV file
results = await client.twitter.search_posts("AI")
csv_url = await results.export_csv()
print(csv_url)
Response Types
Methods that return PaginatedResult support a response_type parameter to control how results are fetched. Import the ResponseType enum:
from xpoz import XpozClient, ResponseType
| Mode | Enum Value | Behavior | Best For |
|---|
| Fast | ResponseType.FAST | Returns up to limit results immediately, no polling | Quick queries, UI previews |
| Paging | ResponseType.PAGING | Async paginated query with full dataset access | Full analysis, large datasets |
| CSV | ResponseType.CSV | Async bulk export, returns download URL via export_csv() | Data exports |
Fast Mode (default)
Returns results immediately without polling. This is the default behavior when response_type is not specified.
results = client.twitter.search_posts(
"bitcoin",
limit=10,
fields=["id", "text", "like_count"],
)
# Equivalent to response_type=ResponseType.FAST
for tweet in results.data:
print(tweet.text)
Fast mode skips async operation polling, making it significantly faster for small result sets. Use it when you need a quick preview or only need a limited number of results.
Paging Mode
Returns full paginated results (100 items per page). Use this when you need to iterate through all results.
results = client.twitter.search_posts(
"bitcoin",
response_type=ResponseType.PAGING,
)
print(results.pagination.total_rows) # total matching rows
CSV Mode
Triggers a server-side CSV export. The result contains no inline data — call export_csv() to get the download URL.
results = client.twitter.search_posts(
"bitcoin",
response_type=ResponseType.CSV,
)
csv_url = results.export_csv()
print(csv_url) # URL to download the CSV file
Methods Supporting Response Types
The following methods accept both response_type and limit:
| Platform | Method |
|---|
| Twitter | search_posts, get_posts_by_author, get_users_by_keywords |
| Instagram | search_posts, get_posts_by_user, get_users_by_keywords |
| Reddit | search_posts |
| TikTok | search_posts, get_posts_by_user, get_users_by_keywords |
limit only (no response_type):
twitter.search_users(), instagram.search_users(), reddit.search_users(), reddit.search_subreddits(), tiktok.search_users()
For the equivalent pagination patterns in TypeScript, see TypeScript SDK Pagination. The TypeScript SDK uses ResponseType.Fast, ResponseType.Paging, and ResponseType.Csv (PascalCase enum values) and camelCase field names. 
