List Smart RAG Nodes - Graphor Docs

Retrieve all smart RAG nodes from a specific flow in your Graphor project. Smart RAG nodes are intelligent RAG (Retrieval-Augmented Generation) components that combine document chunking and retrieval in a single, optimized operation for enhanced performance and simplified workflow management.

Overview

The List Smart RAG Nodes endpoint allows you to retrieve information about smart RAG nodes within a flow. Smart RAG nodes are all-in-one components that automatically handle document processing, chunking, embedding generation, and intelligent retrieval, providing a streamlined approach to building sophisticated RAG pipelines.

Method: GET
URL: https://{flow_name}.flows.graphorlm.com/smart-rag
Authentication: Required (API Token)

Authentication

All requests must include a valid API token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Learn how to generate API tokens in the API Tokens guide.

Request Format

Headers

Header	Value	Required
`Authorization`	`Bearer YOUR_API_TOKEN`	Yes

Parameters

No query parameters are required for this endpoint.

Example Request

GET https://my-rag-pipeline.flows.graphorlm.com/smart-rag
Authorization: Bearer YOUR_API_TOKEN

Response Format

Success Response (200 OK)

The response contains an array of smart RAG node objects:

[
  {
    "id": "smart-rag-1748287628685",
    "type": "smart-rag",
    "position": {
      "x": 500,
      "y": 300
    },
    "style": {
      "height": 200,
      "width": 320
    },
    "data": {
      "name": "Intelligent Document Processing",
      "config": {
        "topK": 10
      },
      "result": {
        "updated": true,
        "processing": false,
        "waiting": false,
        "has_error": false,
        "updatedMetrics": true,
        "total_processed": 1250,
        "total_chunks": 420,
        "total_retrieved": 85
      }
    }
  }
]

Response Structure

Each smart RAG node in the array contains:

Field	Type	Description
`id`	string	Unique identifier for the smart RAG node
`type`	string	Node type (always “smart-rag” for smart RAG nodes)
`position`	object	Position coordinates in the flow canvas
`style`	object	Visual styling properties (height, width)
`data`	object	Smart RAG node configuration and results

Position Object

Field	Type	Description
`x`	number	X coordinate position in the flow canvas
`y`	number	Y coordinate position in the flow canvas

Style Object

Field	Type	Description
`height`	integer	Height of the node in pixels
`width`	integer	Width of the node in pixels

Data Object

Field	Type	Description
`name`	string	Display name of the smart RAG node
`config`	object	Node configuration including retrieval settings
`result`	object	Processing results and status information (optional)

Config Object

Field	Type	Description
`topK`	integer	Number of top results to retrieve during query processing (default: 5)

Result Object (Optional)

Field	Type	Description
`updated`	boolean	Whether the node has been processed with current configuration
`processing`	boolean	Whether the node is currently being processed
`waiting`	boolean	Whether the node is waiting for dependencies
`has_error`	boolean	Whether the node encountered an error during processing
`updatedMetrics`	boolean	Whether evaluation metrics have been computed
`total_processed`	integer	Total number of documents processed (if available)
`total_chunks`	integer	Number of chunks generated during processing (if available)
`total_retrieved`	integer	Number of documents retrieved in recent queries (if available)

Code Examples

JavaScript/Node.js

async function listSmartRagNodes(flowName, apiToken) {
  const response = await fetch(`https://${flowName}.flows.graphorlm.com/smart-rag`, {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiToken}`
    }
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return await response.json();
}

// Usage
listSmartRagNodes('my-rag-pipeline', 'YOUR_API_TOKEN')
  .then(smartRagNodes => {
    console.log(`Found ${smartRagNodes.length} smart RAG node(s)`);
    
    smartRagNodes.forEach(node => {
      console.log(`\nNode: ${node.data.name} (${node.id})`);
      console.log(`Top K Setting: ${node.data.config.topK || 'Default (5)'}`);
      
      if (node.data.result) {
        const status = node.data.result.processing ? 'Processing' : 
                      node.data.result.waiting ? 'Waiting' :
                      node.data.result.has_error ? 'Error' :
                      node.data.result.updated ? 'Updated' : 'Needs Update';
        console.log(`Status: ${status}`);
        
        if (node.data.result.total_processed) {
          console.log(`Documents processed: ${node.data.result.total_processed}`);
        }
        if (node.data.result.total_chunks) {
          console.log(`Chunks generated: ${node.data.result.total_chunks}`);
        }
        if (node.data.result.total_retrieved) {
          console.log(`Documents retrieved: ${node.data.result.total_retrieved}`);
        }
        if (node.data.result.updatedMetrics) {
          console.log(`Metrics: Updated`);
        }
      }
    });
  })
  .catch(error => console.error('Error:', error));

Python

import requests
import json

def list_smart_rag_nodes(flow_name, api_token):
    url = f"https://{flow_name}.flows.graphorlm.com/smart-rag"
    
    headers = {
        "Authorization": f"Bearer {api_token}"
    }
    
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    
    return response.json()

def analyze_smart_rag_nodes(smart_rag_nodes):
    """Analyze smart RAG nodes and provide detailed summary"""
    print(f"🤖 Smart RAG Nodes Analysis")
    print(f"Total smart RAG nodes: {len(smart_rag_nodes)}")
    print("-" * 50)
    
    status_counts = {"updated": 0, "processing": 0, "waiting": 0, "error": 0, "needs_update": 0}
    total_processed = 0
    total_chunks = 0
    total_retrieved = 0
    topk_settings = {}
    
    for node in smart_rag_nodes:
        node_data = node.get('data', {})
        config = node_data.get('config', {})
        result = node_data.get('result', {})
        
        # Track Top K settings
        topk = config.get('topK', 5)  # Default is 5
        topk_settings[topk] = topk_settings.get(topk, 0) + 1
        
        print(f"\n🧠 Node: {node_data.get('name', 'Unnamed')} ({node['id']})")
        print(f"   Top K Setting: {topk}")
        
        if result:
            if result.get('processing'):
                status_counts["processing"] += 1
                print("   🔄 Status: Processing")
            elif result.get('waiting'):
                status_counts["waiting"] += 1
                print("   ⏳ Status: Waiting")
            elif result.get('has_error'):
                status_counts["error"] += 1
                print("   ❌ Status: Error")
            elif result.get('updated'):
                status_counts["updated"] += 1
                print("   ✅ Status: Updated")
            else:
                status_counts["needs_update"] += 1
                print("   ⚠️  Status: Needs Update")
                
            # Accumulate metrics
            if result.get('total_processed'):
                processed = result['total_processed']
                total_processed += processed
                print(f"   📄 Documents processed: {processed}")
                
            if result.get('total_chunks'):
                chunks = result['total_chunks']
                total_chunks += chunks
                print(f"   🧩 Chunks generated: {chunks}")
                
            if result.get('total_retrieved'):
                retrieved = result['total_retrieved']
                total_retrieved += retrieved
                print(f"   🎯 Documents retrieved: {retrieved}")
                
            if result.get('updatedMetrics'):
                print("   📊 Metrics: Updated")
    
    print(f"\n📈 Summary:")
    print(f"   Total documents processed: {total_processed}")
    print(f"   Total chunks generated: {total_chunks}")
    print(f"   Total documents retrieved: {total_retrieved}")
    
    print(f"\n🎯 Top K Settings:")
    for topk, count in sorted(topk_settings.items()):
        print(f"   Top K = {topk}: {count} node(s)")
    
    print(f"\n📊 Node Status:")
    for status, count in status_counts.items():
        if count > 0:
            print(f"   {status.replace('_', ' ').title()}: {count}")

# Usage
try:
    smart_rag_nodes = list_smart_rag_nodes("my-rag-pipeline", "YOUR_API_TOKEN")
    analyze_smart_rag_nodes(smart_rag_nodes)
    
except requests.exceptions.HTTPError as e:
    print(f"Error: {e}")
    if e.response.status_code == 404:
        print("Flow not found or no smart RAG nodes in this flow")
    elif e.response.status_code == 401:
        print("Invalid API token or insufficient permissions")

cURL

# Basic request
curl -X GET https://my-rag-pipeline.flows.graphorlm.com/smart-rag \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# With jq for formatted output
curl -X GET https://my-rag-pipeline.flows.graphorlm.com/smart-rag \
  -H "Authorization: Bearer YOUR_API_TOKEN" | jq '.'

# Extract smart RAG configuration summary
curl -X GET https://my-rag-pipeline.flows.graphorlm.com/smart-rag \
  -H "Authorization: Bearer YOUR_API_TOKEN" | \
  jq -r '.[] | "\(.data.name): Top K = \(.data.config.topK // 5)"'

# Count total processed documents across all nodes
curl -X GET https://my-rag-pipeline.flows.graphorlm.com/smart-rag \
  -H "Authorization: Bearer YOUR_API_TOKEN" | \
  jq '[.[] | .data.result.total_processed // 0] | add'

# Get nodes with metrics enabled
curl -X GET https://my-rag-pipeline.flows.graphorlm.com/smart-rag \
  -H "Authorization: Bearer YOUR_API_TOKEN" | \
  jq '.[] | select(.data.result.updatedMetrics == true) | .data.name'

Error Responses

Common Error Codes

Status Code	Description	Example Response
401	Unauthorized - Invalid or missing API token	`{"detail": "Invalid authentication credentials"}`
404	Not Found - Flow not found	`{"detail": "Flow not found"}`
500	Internal Server Error - Server error	`{"detail": "Failed to retrieve smart RAG nodes"}`

Error Response Format

{
  "detail": "Error message describing what went wrong"
}

Example Error Responses

Invalid API Token

{
  "detail": "Invalid authentication credentials"
}

Flow Not Found

{
  "detail": "Flow not found"
}

Server Error

{
  "detail": "Failed to retrieve smart RAG nodes"
}

Use Cases

Smart RAG Node Management

Use this endpoint to:

Configuration Overview: Review smart RAG settings and Top K configurations
Performance Monitoring: Check processing status and document processing metrics
Flow Analysis: Understand the intelligent RAG components in your pipeline
Metrics Evaluation: Monitor retrieval quality and processing effectiveness

Integration Examples

Smart RAG Performance Monitor

class SmartRagPerformanceMonitor {
  constructor(flowName, apiToken) {
    this.flowName = flowName;
    this.apiToken = apiToken;
  }

  async getPerformanceReport() {
    try {
      const nodes = await this.listSmartRagNodes();
      const report = {
        totalNodes: nodes.length,
        activeNodes: 0,
        processingNodes: 0,
        errorNodes: 0,
        totalProcessed: 0,
        totalChunks: 0,
        totalRetrieved: 0,
        avgTopK: 0,
        topKDistribution: {},
        performance: []
      };

      let totalTopK = 0;
      let nodeCount = 0;

      for (const node of nodes) {
        const config = node.data.config || {};
        const result = node.data.result || {};
        
        // Track Top K settings
        const topK = config.topK || 5;
        report.topKDistribution[topK] = (report.topKDistribution[topK] || 0) + 1;
        totalTopK += topK;
        nodeCount++;
        
        // Accumulate metrics
        if (result.total_processed) report.totalProcessed += result.total_processed;
        if (result.total_chunks) report.totalChunks += result.total_chunks;
        if (result.total_retrieved) report.totalRetrieved += result.total_retrieved;
        
        // Track node status
        if (result.processing) {
          report.processingNodes++;
        } else if (result.has_error) {
          report.errorNodes++;
        } else if (result.updated) {
          report.activeNodes++;
        }
        
        // Individual node performance
        report.performance.push({
          nodeId: node.id,
          nodeName: node.data.name,
          topK: topK,
          totalProcessed: result.total_processed || 0,
          totalChunks: result.total_chunks || 0,
          totalRetrieved: result.total_retrieved || 0,
          hasMetrics: result.updatedMetrics || false,
          status: result.processing ? 'Processing' :
                 result.has_error ? 'Error' :
                 result.updated ? 'Active' : 'Inactive'
        });
      }

      if (nodeCount > 0) {
        report.avgTopK = Math.round(totalTopK / nodeCount);
      }

      return report;
    } catch (error) {
      throw new Error(`Performance report failed: ${error.message}`);
    }
  }

  async listSmartRagNodes() {
    const response = await fetch(`https://${this.flowName}.flows.graphorlm.com/smart-rag`, {
      headers: { 'Authorization': `Bearer ${this.apiToken}` }
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    return await response.json();
  }

  async generateReport() {
    const report = await this.getPerformanceReport();
    
    console.log('🤖 Smart RAG Performance Report');
    console.log('================================');
    console.log(`Total Nodes: ${report.totalNodes}`);
    console.log(`Active Nodes: ${report.activeNodes}`);
    console.log(`Processing Nodes: ${report.processingNodes}`);
    console.log(`Error Nodes: ${report.errorNodes}`);
    console.log(`Total Documents Processed: ${report.totalProcessed}`);
    console.log(`Total Chunks Generated: ${report.totalChunks}`);
    console.log(`Total Documents Retrieved: ${report.totalRetrieved}`);
    console.log(`Average Top K: ${report.avgTopK}`);
    
    console.log('\n🎯 Top K Distribution:');
    for (const [topK, count] of Object.entries(report.topKDistribution)) {
      console.log(`  Top K = ${topK}: ${count} node(s)`);
    }
    
    console.log('\n📊 Node Performance:');
    report.performance.forEach(node => {
      console.log(`  ${node.nodeName} (${node.nodeId}):`);
      console.log(`    Top K: ${node.topK}, Status: ${node.status}`);
      console.log(`    Processed: ${node.totalProcessed}, Chunks: ${node.totalChunks}`);
      console.log(`    Retrieved: ${node.totalRetrieved}, Metrics: ${node.hasMetrics ? 'Yes' : 'No'}`);
    });

    return report;
  }
}

// Usage
const monitor = new SmartRagPerformanceMonitor('my-rag-pipeline', 'YOUR_API_TOKEN');
monitor.generateReport().catch(console.error);

Configuration Optimizer

import requests
from typing import List, Dict, Any

class SmartRagConfigOptimizer:
    def __init__(self, flow_name: str, api_token: str):
        self.flow_name = flow_name
        self.api_token = api_token
        self.base_url = f"https://{flow_name}.flows.graphorlm.com"
    
    def get_smart_rag_nodes(self) -> List[Dict[str, Any]]:
        """Retrieve all smart RAG nodes from the flow"""
        response = requests.get(
            f"{self.base_url}/smart-rag",
            headers={"Authorization": f"Bearer {self.api_token}"}
        )
        response.raise_for_status()
        return response.json()
    
    def analyze_configurations(self) -> Dict[str, Any]:
        """Analyze smart RAG node configurations and provide optimization recommendations"""
        nodes = self.get_smart_rag_nodes()
        
        analysis_report = {
            "summary": {
                "total_nodes": len(nodes),
                "active_nodes": 0,
                "nodes_with_metrics": 0,
                "avg_top_k": 0,
                "total_throughput": 0
            },
            "nodes": [],
            "recommendations": []
        }
        
        total_top_k = 0
        node_count = 0
        total_processed = 0
        
        for node in nodes:
            node_info = {
                "id": node["id"],
                "name": node["data"]["name"],
                "config": node["data"]["config"],
                "result": node["data"].get("result", {}),
                "recommendations": []
            }
            
            config = node["data"]["config"]
            result = node["data"].get("result", {})
            
            # Analyze Top K setting
            top_k = config.get("topK", 5)
            total_top_k += top_k
            node_count += 1
            
            # Analyze performance
            if result.get("total_processed"):
                total_processed += result["total_processed"]
                analysis_report["summary"]["total_throughput"] += result["total_processed"]
            
            # Track active nodes
            if result.get("updated"):
                analysis_report["summary"]["active_nodes"] += 1
            
            # Track metrics
            if result.get("updatedMetrics"):
                analysis_report["summary"]["nodes_with_metrics"] += 1
            
            # Generate recommendations
            if top_k > 20:
                node_info["recommendations"].append(
                    "Consider reducing Top K for better performance - current value may be too high"
                )
            elif top_k < 3:
                node_info["recommendations"].append(
                    "Consider increasing Top K for better coverage - current value may be too low"
                )
            
            if not result.get("updatedMetrics"):
                node_info["recommendations"].append(
                    "Enable metrics evaluation to monitor retrieval quality"
                )
            
            if result.get("has_error"):
                node_info["recommendations"].append(
                    "Node has errors - check configuration and input dependencies"
                )
            
            analysis_report["nodes"].append(node_info)
        
        # Calculate averages
        if node_count > 0:
            analysis_report["summary"]["avg_top_k"] = round(total_top_k / node_count, 1)
        
        # Global recommendations
        if analysis_report["summary"]["nodes_with_metrics"] < len(nodes):
            analysis_report["recommendations"].append(
                "Consider enabling metrics on all nodes for better monitoring"
            )
        
        if analysis_report["summary"]["avg_top_k"] > 15:
            analysis_report["recommendations"].append(
                "Average Top K is high - consider optimizing for better resource efficiency"
            )
        
        return analysis_report
    
    def print_analysis_report(self, report: Dict[str, Any]):
        """Print a formatted analysis report"""
        summary = report["summary"]
        
        print("🔍 Smart RAG Configuration Analysis")
        print("=" * 50)
        print(f"Flow: {self.flow_name}")
        print(f"Total Nodes: {summary['total_nodes']}")
        print(f"Active Nodes: {summary['active_nodes']}")
        print(f"Nodes with Metrics: {summary['nodes_with_metrics']}")
        print(f"Average Top K: {summary['avg_top_k']}")
        print(f"Total Throughput: {summary['total_throughput']} documents")
        
        print(f"\n📋 Node Analysis:")
        print("-" * 30)
        for node in report["nodes"]:
            print(f"\n🧠 {node['name']} ({node['id']})")
            print(f"   Top K: {node['config'].get('topK', 5)}")
            
            result = node["result"]
            if result.get('updated'):
                print("   ✅ Status: Updated")
            elif result.get('processing'):
                print("   🔄 Status: Processing")
            else:
                print("   ⚠️  Status: Needs Update")
            
            if result.get('total_processed'):
                print(f"   📄 Processed: {result['total_processed']} documents")
            
            if result.get('updatedMetrics'):
                print("   📊 Metrics: Enabled")
            
            for recommendation in node["recommendations"]:
                print(f"   💡 {recommendation}")
        
        if report["recommendations"]:
            print(f"\n🎯 Global Recommendations:")
            for rec in report["recommendations"]:
                print(f"   • {rec}")

# Usage
optimizer = SmartRagConfigOptimizer("my-rag-pipeline", "YOUR_API_TOKEN")
try:
    report = optimizer.analyze_configurations()
    optimizer.print_analysis_report(report)
except Exception as e:
    print(f"Analysis failed: {e}")

Best Practices

Configuration Management

Optimal Top K: Start with default values (5-10) and adjust based on quality requirements
Performance Monitoring: Regularly check processing metrics and retrieval effectiveness
Metrics Evaluation: Enable metrics on all nodes to track RAG pipeline quality
Resource Management: Balance Top K values with system performance requirements

Performance Optimization

Integrated Processing: Leverage smart RAG’s combined chunking + retrieval for simplified workflows
Batch Operations: Monitor processing efficiency across multiple documents
Quality Assessment: Use built-in metrics to evaluate retrieval relevance
Resource Planning: Consider processing time and resource consumption for large document sets

Monitoring and Maintenance

Regular Health Checks: Monitor smart RAG nodes for processing completion and errors
Configuration Validation: Verify that Top K settings align with your quality requirements
Performance Tracking: Monitor throughput metrics and processing times
Quality Monitoring: Track retrieval effectiveness through updated metrics

Troubleshooting

Flow Not Found Error

Solution: Verify that:

The flow name in the URL is correct and matches exactly
The flow exists in your project
Your API token has access to the correct project
The flow has been created and saved properly

Empty Smart RAG Nodes Array

Solution: If no smart RAG nodes are returned:

Verify the flow contains smart RAG components
Check that smart RAG nodes have been added to the flow
Ensure the flow has been saved after adding smart RAG nodes
Confirm you’re checking the correct flow

Invalid Configuration Settings

Solution: If smart RAG nodes have invalid configurations:

Verify Top K is a positive integer or null
Ensure Top K value is reasonable for your use case (typically 1-50)
Check that input nodes (datasets) are properly configured
Validate that the node has proper connections to data sources

Processing Status Issues

Solution: If nodes show persistent processing or error status:

Check if processing is taking longer due to large document volumes
Verify that upstream dataset nodes are configured correctly
Monitor system resources and processing capacity
Review error logs for specific processing issues

Missing Metrics Data

Solution: If nodes show updatedMetrics: false:

Ensure evaluation data (questions/testsets) are connected to the node
Re-run the flow to trigger metrics computation
Check that the evaluation process completed successfully
Verify that evaluation inputs are properly formatted

Connection Issues

Solution: For connectivity problems:

Check your internet connection
Verify the flow URL is accessible
Ensure your firewall allows HTTPS traffic to *.flows.graphorlm.com
Try accessing the endpoint from a different network

Next Steps

After retrieving smart RAG node information, you might want to:

Update Smart RAG Configuration

Modify smart RAG node settings like Top K retrieval parameters

List Dataset Nodes

View dataset nodes that provide input to smart RAG nodes

Run Flow

Execute your flow with the configured smart RAG nodes

Flow Overview

Learn about all available flow management endpoints

Get Started

Data API Options

RAG Pipelines API

​Overview

​Authentication

​Request Format

​Headers

​Parameters

​Example Request

​Response Format

​Success Response (200 OK)

​Response Structure

​Position Object

​Style Object

​Data Object

​Config Object

​Result Object (Optional)

​Code Examples

​JavaScript/Node.js

​Python

​cURL

​Error Responses

​Common Error Codes

​Error Response Format

​Example Error Responses

​Invalid API Token

​Flow Not Found

​Server Error

​Use Cases

​Smart RAG Node Management

​Integration Examples

​Smart RAG Performance Monitor

​Configuration Optimizer

​Best Practices

​Configuration Management

​Performance Optimization

​Monitoring and Maintenance

​Troubleshooting

​Next Steps

Update Smart RAG Configuration

List Dataset Nodes

Run Flow

Flow Overview

Overview

Authentication

Request Format

Headers

Parameters

Example Request

Response Format

Success Response (200 OK)

Response Structure

Position Object

Style Object

Data Object

Config Object

Result Object (Optional)

Code Examples

JavaScript/Node.js

Python

cURL

Error Responses

Common Error Codes

Error Response Format

Example Error Responses

Invalid API Token

Flow Not Found

Server Error

Use Cases

Smart RAG Node Management

Integration Examples

Smart RAG Performance Monitor

Configuration Optimizer

Best Practices

Configuration Management

Performance Optimization

Monitoring and Maintenance

Troubleshooting

Next Steps