Skip to main content
When you use responseType: "paging", the Xpoz MCP server creates a server-side cached table and returns results 100 items per page. This enables efficient iteration through large datasets without re-executing the underlying query.

​
How It Works

1. First call (with responseType: "paging")
   ├── Server executes the query
   ├── Creates a cached pagination table
   ├── Returns page 1 + metadata
   └── tableName: "op_getTwitterPostsByKeywords_1718..."

2. Subsequent calls (with tableName + pageNumber)
   ├── Server looks up the cached table
   ├── Returns the requested page (O(1) lookup)
   └── No query re-execution needed

​
First Call

Set responseType to "paging" on your initial request. The response includes pagination metadata alongside the first page of results. Example — search Twitter posts: 
{
  "tool": "getTwitterPostsByKeywords",
  "arguments": {
    "query": "artificial intelligence",
    "responseType": "paging"
  }
}
Response metadata:
FieldTypeDescription
tableNamestringIdentifier for the cached pagination table
totalPagesnumberTotal number of pages available
totalRowsnumberTotal number of matching results
pageSizenumberItems per page (always 100)
pageNumbernumberCurrent page number (1 on first call)

​
Fetching Additional Pages

Pass the tableName from the first response along with the desired pageNumber: 
{
  "tool": "getTwitterPostsByKeywords",
  "arguments": {
    "tableName": "op_getTwitterPostsByKeywords_1718123456_abc",
    "pageNumber": 2
  }
}
When fetching subsequent pages, you only need tableName and pageNumber. The original query parameters are not required — the cached table already contains the full result set.

​
Iterating Through All Pages

A typical pattern for retrieving all results: 
Step 1: Call tool with responseType: "paging"
        → Get tableName, totalPages, page 1 data

Step 2: Loop from page 2 to totalPages
        → Call tool with tableName + pageNumber
        → Process each page of results

Step 3: All data retrieved
Example conversation flow: 
Agent: I'll search for AI-related tweets and iterate through all results.

Call 1: getTwitterPostsByKeywords(query: "AI", responseType: "paging")
→ tableName: "op_..._abc", totalPages: 5, totalRows: 487, page 1 (100 items)

Call 2: getTwitterPostsByKeywords(tableName: "op_..._abc", pageNumber: 2)
→ page 2 (100 items)

Call 3: getTwitterPostsByKeywords(tableName: "op_..._abc", pageNumber: 3)
→ page 3 (100 items)

Call 4: getTwitterPostsByKeywords(tableName: "op_..._abc", pageNumber: 4)
→ page 4 (100 items)

Call 5: getTwitterPostsByKeywords(tableName: "op_..._abc", pageNumber: 5)
→ page 5 (87 items)

​
Bulk Page Fetching

Some tools support fetching multiple pages at once using the pageNumberEnd parameter: 
{
  "tool": "getTwitterPostsByKeywords",
  "arguments": {
    "tableName": "op_..._abc",
    "pageNumber": 1,
    "pageNumberEnd": 5
  }
}
This returns pages 1 through 5 in a single response, reducing the number of round trips.

​
Page Size

All paginated tools use a fixed page size of 100 items per page. User connection tools (getTwitterUserConnections, getInstagramUserConnections) use 1,000 users per page with default fields.

​
Table Lifecycle

Cached pagination tables are temporary and managed automatically:
  • Tables are created when the first paging request is made
  • The server handles cleanup automatically
  • If a table expires or is not found, re-issue the original query with responseType: "paging" to create a new one
Do not store tableName values for long-term use. They are temporary identifiers tied to a specific query execution. Always be prepared to re-query if a table is no longer available.
  • Response Modes — Choosing between fast, paging, and CSV
  • Field Selection — Reduce page payload size by selecting specific fields
  • Operations — Long-running operations that produce paginated results