Overview
The List Reranking Nodes endpoint allows you to retrieve information about reranking nodes within a flow. Reranking nodes process documents retrieved by previous stages, using sophisticated LLM-based scoring to reorder results by relevance, ensuring that the most appropriate content appears first in your RAG pipeline.- Method:
GET
- URL:
https://{flow_name}.flows.graphorlm.com/reranking
- Authentication: Required (API Token)
Authentication
All requests must include a valid API token in the Authorization header: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
Response Format
Success Response (200 OK)
The response contains an array of reranking node objects:Response Structure
Each reranking node in the array contains:Field | Type | Description |
---|---|---|
id | string | Unique identifier for the reranking node |
type | string | Node type (always “reranking” for reranking nodes) |
position | object | Position coordinates in the flow canvas |
style | object | Visual styling properties (height, width) |
data | object | Reranking 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 reranking node |
config | object | Node configuration including reranking parameters |
result | object | Processing results and reranking metrics (optional) |
Config Object
Field | Type | Description |
---|---|---|
topK | integer | Maximum number of documents to return after reranking (optional) |
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 reranking metrics have been calculated |
total_reranked | integer | Number of documents processed through reranking (if available) |
Code Examples
JavaScript/Node.js
Python
cURL
PHP
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 reranking nodes"} |
Error Response Format
Example Error Responses
Invalid API Token
Flow Not Found
Server Error
Use Cases
Reranking Node Management
Use this endpoint to:- Performance Monitoring: Review reranking effectiveness and processing metrics
- Configuration Analysis: Examine Top K settings and optimization opportunities
- Quality Assurance: Monitor reranking accuracy and relevance improvements
- Flow Optimization: Analyze reranking impact on overall pipeline performance
- Debugging: Identify issues with reranking processing or LLM integration
Integration Examples
Reranking Quality Monitor
Reranking Performance Analyzer
Best Practices
Configuration Management
- Optimal Top K: Set Top K between 5-20 for most applications; use unlimited only when necessary
- Performance Monitoring: Regularly check reranking metrics and processing times
- Quality Assessment: Monitor improvement in result relevance after reranking
- Resource Planning: Consider LLM resource usage and processing time for reranking operations
Performance Optimization
- Batch Processing: Leverage built-in parallel processing for efficiency
- Top K Tuning: Balance quality improvement with processing time and resource usage
- Error Handling: Monitor retry mechanisms and processing errors
- Metrics Tracking: Keep reranking metrics updated for performance analysis
Quality Assurance
- Regular Auditing: Monitor reranking node configurations for consistency
- Result Validation: Compare pre and post-reranking result quality
- A/B Testing: Test different Top K values to optimize for your use case
- Feedback Integration: Use user feedback to validate reranking effectiveness
Troubleshooting
Flow Not Found Error
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 Reranking Nodes Array
Empty Reranking Nodes Array
Solution: If no reranking nodes are returned:
- Verify the flow contains reranking components
- Check that reranking nodes have been added to the flow
- Ensure the flow has been saved after adding reranking nodes
- Confirm you’re checking the correct flow
Poor Reranking Performance
Poor Reranking Performance
Solution: If reranking is not improving results:
- Check that retrieval nodes are providing quality input
- Verify LLM integration is working properly
- Monitor reranking scores and positions
- Consider adjusting Top K based on content quality
Slow Processing Times
Slow Processing Times
Solution: If reranking is taking too long:
- Reduce Top K to process fewer documents
- Check LLM service response times
- Monitor batch processing efficiency
- Consider system resource allocation
Connection Issues
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