get_page_references
Retrieve blocks referencing a specific Roam Research page, sorted by recency, with full hierarchical context and pagination support for large datasets.
Instructions
Get all blocks that reference a specific page in Roam Research with pagination support.
Finds all blocks across your Roam database that contain links to the specified page.
Results are sorted by most recent edit time and include the full hierarchical context
of each referencing block.
Args:
page_name: Exact name of the page to find references for (case-sensitive)
limit: Maximum number of references to return per request (default: 10)
cursor: Timestamp cursor for pagination - use next_cursor from previous response
to get additional results
Returns:
JSON string containing:
- result: Array of referencing blocks with content and timestamps
- next_cursor: Timestamp for pagination (if more results available)
- total_matches: Number of references found in this batch
Examples:
get_page_references("GTD")
get_page_references("Project Alpha", limit=20)
get_page_references("Meeting Notes", limit=5, cursor=1640995200000)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | ||
| limit | No | ||
| page_name | Yes |
Implementation Reference
- main.py:419-450 (handler)MCP tool handler function for 'get_page_references', decorated with @mcp.tool(). Includes type hints serving as input schema, comprehensive docstring describing parameters and return format, and delegates to internal client implementation.@mcp.tool() async def get_page_references(page_name: str, limit: int = 10, cursor: Optional[int] = None) -> str: """Get all blocks that reference a specific page in Roam Research with pagination support. Finds all blocks across your Roam database that contain links to the specified page. Results are sorted by most recent edit time and include the full hierarchical context of each referencing block. Args: page_name: Exact name of the page to find references for (case-sensitive) limit: Maximum number of references to return per request (default: 10) cursor: Timestamp cursor for pagination - use next_cursor from previous response to get additional results Returns: JSON string containing: - result: Array of referencing blocks with content and timestamps - next_cursor: Timestamp for pagination (if more results available) - total_matches: Number of references found in this batch Examples: get_page_references("GTD") get_page_references("Project Alpha", limit=20) get_page_references("Meeting Notes", limit=5, cursor=1640995200000) """ try: client = get_roam_client() result = client.get_page_references(page_name, limit, cursor) return json.dumps(result, indent=2) except Exception as e: print(f"Error getting page references: {e}", file=sys.stderr) return f"Error: {str(e)}"
- main.py:130-209 (helper)Core implementation of get_page_references in RoamResearchMCPServer class. Executes Datalog queries against Roam API to find blocks referencing the page, handles cursor-based pagination, sorts by edit time descending, limits results, builds hierarchical markdown content using _build_block_with_children, and formats output with next_cursor for pagination.def get_page_references(self, page_name: str, limit: int = 10, cursor: Optional[int] = None) -> Dict[str, Any]: """Get references to a specific page with markdown content and child blocks""" # Build the query with time-based sorting and pagination if cursor: # Use cursor-based pagination for subsequent pages query = """[:find (pull ?ref [:block/string :block/uid :edit/time {:block/children [:block/string :block/uid :edit/time {:block/children [:block/string :block/uid :edit/time {:block/children [:block/string :block/uid :edit/time {:block/children [:block/string :block/uid :edit/time]}]}]}]}]) ?time :in $ ?PAGE ?cursor-time :where [?page :node/title ?PAGE] [?ref :block/refs ?page] [?ref :edit/time ?time] [(< ?time ?cursor-time)] ]""" data = {"query": query, "args": [page_name, cursor]} else: # First page - no cursor query = """[:find (pull ?ref [:block/string :block/uid :edit/time {:block/children [:block/string :block/uid :edit/time {:block/children [:block/string :block/uid :edit/time {:block/children [:block/string :block/uid :edit/time {:block/children [:block/string :block/uid :edit/time]}]}]}]}]) ?time :in $ ?PAGE :where [?page :node/title ?PAGE] [?ref :block/refs ?page] [?ref :edit/time ?time] ]""" data = {"query": query, "args": [page_name]} endpoint = f"/api/graph/{self.graph_name}/q" raw_result = self._make_request("POST", endpoint, data) # Sort by time (descending) and apply limit results = raw_result.get("result", []) sorted_results = sorted(results, key=lambda x: x[1], reverse=True) limited_results = sorted_results[:limit] # Transform the result to only include markdown content with children simplified_result = [] next_cursor = None for item in limited_results: if item and len(item) > 0: block = item[0] timestamp = item[1] content = self._build_block_with_children(block) simplified_result.append({"content": content, "timestamp": timestamp}) next_cursor = timestamp result = {"result": simplified_result} # Add next_cursor if there are more results if len(results) > limit: result["next_cursor"] = next_cursor return result
- main.py:419-419 (registration)Registration of the 'get_page_references' tool using the @mcp.tool() decorator.@mcp.tool()