Some queries — especially large pagination or CSV export jobs — run as background operations. The Xpoz MCP server provides two tools for managing these: checkOperationStatus and cancelOperation.
How Operations Work
When a tool triggers a long-running task, it returns an operation ID instead of immediate results. Your agent then polls for completion using checkOperationStatus.
1. Agent calls a tool (e.g., large paging query)
└── Server returns: operationId, status: "running"
2. Agent polls checkOperationStatus(operationId)
└── Server returns: status: "running"
3. Agent polls again
└── Server returns: status: "completed", results: [...]
Most AI agents handle this polling automatically. You typically don’t need to manage operations manually — just call a tool and your agent retrieves the results when ready.
Operation States
| State | Description |
|---|
running | Operation is actively executing |
completed | Successfully finished — results are available |
failed | An error occurred during execution |
cancelled | Gracefully stopped by a cancelOperation call |
checkOperationStatus
Polls the status of an async operation and retrieves results when complete.
| Parameter | Type | Required | Description |
|---|
operationId | string | Yes | The operation ID returned by the initiating tool call |
Returns the operation results:
- For query operations: Paginated results with data
- For CSV export operations: An S3 download URL
{
"status": "completed",
"message": "Operation completed successfully. Processed 487 items.",
"results": [...]
}
Returns the current status with elapsed time:{
"status": "running",
"message": "Processing... 250 processed",
"duration": 12
}
Returns the error details:{
"status": "failed",
"message": "Operation failed: Connection timeout"
}
cancelOperation
Gracefully stops a running operation.
| Parameter | Type | Required | Description |
|---|
operationId | string | Yes | The operation ID to cancel |
running status. The operation stops at its next processing checkpoint.
If you receive an error that an operation was not found, it may have expired. Re-issue the original query to start a new operation.
- Response Modes — CSV mode triggers async operations for large exports
- Pagination — Paging mode may trigger operations for large result sets
