Retrieve all smart RAG nodes from a specific flow in your GraphorLM 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

HeaderValueRequired
AuthorizationBearer YOUR_API_TOKENYes

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:
FieldTypeDescription
idstringUnique identifier for the smart RAG node
typestringNode type (always “smart-rag” for smart RAG nodes)
positionobjectPosition coordinates in the flow canvas
styleobjectVisual styling properties (height, width)
dataobjectSmart RAG node configuration and results

Position Object

FieldTypeDescription
xnumberX coordinate position in the flow canvas
ynumberY coordinate position in the flow canvas

Style Object

FieldTypeDescription
heightintegerHeight of the node in pixels
widthintegerWidth of the node in pixels

Data Object

FieldTypeDescription
namestringDisplay name of the smart RAG node
configobjectNode configuration including retrieval settings
resultobjectProcessing results and status information (optional)

Config Object

FieldTypeDescription
topKintegerNumber of top results to retrieve during query processing (default: 5)

Result Object (Optional)

FieldTypeDescription
updatedbooleanWhether the node has been processed with current configuration
processingbooleanWhether the node is currently being processed
waitingbooleanWhether the node is waiting for dependencies
has_errorbooleanWhether the node encountered an error during processing
updatedMetricsbooleanWhether evaluation metrics have been computed
total_processedintegerTotal number of documents processed (if available)
total_chunksintegerNumber of chunks generated during processing (if available)
total_retrievedintegerNumber 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'

PHP

<?php
function listSmartRagNodes($flowName, $apiToken) {
    $url = "https://{$flowName}.flows.graphorlm.com/smart-rag";
    
    $options = [
        'http' => [
            'header' => "Authorization: Bearer {$apiToken}",
            'method' => 'GET'
        ]
    ];
    
    $context = stream_context_create($options);
    $result = file_get_contents($url, false, $context);
    
    if ($result === FALSE) {
        throw new Exception('Failed to retrieve smart RAG nodes');
    }
    
    return json_decode($result, true);
}

function analyzeSmartRagNodes($smartRagNodes) {
    $topkSettings = [];
    $statusCounts = [
        'updated' => 0,
        'processing' => 0, 
        'waiting' => 0,
        'error' => 0,
        'needs_update' => 0
    ];
    $totalProcessed = 0;
    $totalChunks = 0;
    $totalRetrieved = 0;
    
    echo "🤖 Smart RAG Nodes Analysis\n";
    echo "Total smart RAG nodes: " . count($smartRagNodes) . "\n";
    echo str_repeat("-", 50) . "\n";
    
    foreach ($smartRagNodes as $node) {
        $data = $node['data'] ?? [];
        $config = $data['config'] ?? [];
        $result = $data['result'] ?? [];
        
        $topK = $config['topK'] ?? 5;
        $topkSettings[$topK] = ($topkSettings[$topK] ?? 0) + 1;
        
        echo "\n🧠 Node: " . ($data['name'] ?? 'Unnamed') . " ({$node['id']})\n";
        echo "   Top K Setting: {$topK}\n";
        
        if (!empty($result)) {
            if ($result['processing'] ?? false) {
                $statusCounts['processing']++;
                echo "   🔄 Status: Processing\n";
            } elseif ($result['waiting'] ?? false) {
                $statusCounts['waiting']++;
                echo "   ⏳ Status: Waiting\n";
            } elseif ($result['has_error'] ?? false) {
                $statusCounts['error']++;
                echo "   ❌ Status: Error\n";
            } elseif ($result['updated'] ?? false) {
                $statusCounts['updated']++;
                echo "   ✅ Status: Updated\n";
            } else {
                $statusCounts['needs_update']++;
                echo "   ⚠️  Status: Needs Update\n";
            }
            
            if (isset($result['total_processed'])) {
                $processed = $result['total_processed'];
                $totalProcessed += $processed;
                echo "   📄 Documents processed: {$processed}\n";
            }
            
            if (isset($result['total_chunks'])) {
                $chunks = $result['total_chunks'];
                $totalChunks += $chunks;
                echo "   🧩 Chunks generated: {$chunks}\n";
            }
            
            if (isset($result['total_retrieved'])) {
                $retrieved = $result['total_retrieved'];
                $totalRetrieved += $retrieved;
                echo "   🎯 Documents retrieved: {$retrieved}\n";
            }
            
            if ($result['updatedMetrics'] ?? false) {
                echo "   📊 Metrics: Updated\n";
            }
        }
    }
    
    echo "\n📈 Summary:\n";
    echo "   Total documents processed: {$totalProcessed}\n";
    echo "   Total chunks generated: {$totalChunks}\n";
    echo "   Total documents retrieved: {$totalRetrieved}\n";
    
    echo "\n🎯 Top K Settings:\n";
    ksort($topkSettings);
    foreach ($topkSettings as $topK => $count) {
        echo "   Top K = {$topK}: {$count} node(s)\n";
    }
    
    echo "\n📊 Node Status:\n";
    foreach ($statusCounts as $status => $count) {
        if ($count > 0) {
            $statusLabel = ucwords(str_replace('_', ' ', $status));
            echo "   {$statusLabel}: {$count}\n";
        }
    }
}

// Usage
try {
    $smartRagNodes = listSmartRagNodes('my-rag-pipeline', 'YOUR_API_TOKEN');
    analyzeSmartRagNodes($smartRagNodes);
    
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>

Error Responses

Common Error Codes

Status CodeDescriptionExample Response
401Unauthorized - Invalid or missing API token{"detail": "Invalid authentication credentials"}
404Not Found - Flow not found{"detail": "Flow not found"}
500Internal 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

Next Steps

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