List all sources in your project using the Graphor SDK
The list method returns every source in the project. Each item includes file metadata (ID, name, size, type, origin), its folder, current processing status, and a human-readable message. You can optionally filter by file_ids and by folder.
Method overview
Python
TypeScript
client.sources.list()
await client.sources.list()
Method signature
Python
TypeScript
client.sources.list( file_ids: list[str] | None = None, # Optional: filter by these file IDs folder: str = omit, # Optional: filter by folder ("" or "/" is the top level) recursive: bool = omit, # Optional: include subfolders (default True) timeout: float | None = None) -> list[PublicSource]
await client.sources.list({ file_ids?: string[] | null, // Optional: filter by these file IDs folder?: string, // Optional: filter by folder ('' or '/' is the top level) recursive?: boolean, // Optional: include subfolders (default true)}): Promise<PublicSource[]>
Parameters
Python
TypeScript
Parameter
Type
Description
Required
file_ids
list[str] | None
If provided, only sources whose file_id is in this list are returned
No
folder
str
Only the sources in this folder and, with recursive, below it. "" or "/" lists only the top level. See Filter by folder.
No
recursive
bool
Default True. With folder, whether the folders below it are included. Without folder, False lists only the top level.
No
timeout
float
Request timeout in seconds
No
Parameter
Type
Description
Required
file_ids
string[] | null
If provided, only sources with these file_ids are returned
No
folder
string
Only the sources in this folder and, with recursive, below it. '' or '/' lists only the top level. See Filter by folder.
No
recursive
boolean
Default true. With folder, whether the folders below it are included. Without folder, false lists only the top level.
No
When no filter is given, the method returns all sources in the project. The filters combine: file_ids with folder returns the listed sources that are in the folder.
Folders are available on the REST API today. In the SDKs they land in the next releases: Python graphor 0.28.0, TypeScript graphor 0.25.0 and the MCP package graphor-mcp 0.25.0. The folder methods, parameters and response fields shown for the SDKs need those versions or later; the hosted remote MCP server offers the folder tools once it runs graphor-mcp 0.25.0.
Response
The method returns a list of source objects. Each has:
Property
Type
Description
status
str
Current processing status (capitalized: e.g. New, Processing, Processed, Completed, Failed)
message
str
Human-readable status message
file_id
str
Unique identifier for the source (use for reprocess, get elements, delete, ask, extract)
file_name
str
Display name of the source file or identifier
file_size
int
Size in bytes (0 for URL/GitHub/YouTube)
file_type
str
File extension or type
file_source
str
Origin: local file, url, github, or youtube
project_id
str
UUID of the project
project_name
str
Name of the project
method
str | null
Partition method: auto, fast, balanced, accurate, or agentic (when available)
folder
str
The folder the source is in, as a /-separated path; "" is the top level
Status values
Backend returns status with capital letters. Typical values:
Status
Description
New
Upload/ingestion accepted; processing has not started yet
Processing
Pipeline is running
Processed
Source has been processed (intermediate or final state)
Completed
Ready for ask, extract, retrieve, and get elements
Failed / Processing failed
Processing encountered an error; consider reprocessing
unknown
Status could not be determined
File Source Types
Source Type
Description
Typical Use Cases
local file
Files uploaded directly from your computer
Documents, PDFs, images, spreadsheets
url
Content imported from web URLs
Web pages, articles, online documents
github
Content imported from GitHub repositories
Code documentation, README files, wikis
youtube
Content imported from YouTube videos
Video transcripts, educational content
Code Examples
Basic Usage
Python
TypeScript
from graphor import Graphorclient = Graphor()# List all sources in the projectsources = client.sources.list()print(f"Found {len(sources)} sources")for source in sources: print(f"{source.file_name} - {source.status}")
import Graphor from 'graphor';const client = new Graphor();// List all sources in the projectconst sources = await client.sources.list();console.log(`Found ${sources.length} sources`);for (const source of sources) { console.log(`${source.file_name} - ${source.status}`);}
every source (recursive=False: only the top level)
folder="Contracts"
the sources in Contracts and in every folder below it
folder="Contracts", recursive=False
only the sources directly in Contracts
folder="" or folder="/"
only the sources at the top level
Matching is exact (Contracts does not match Contracts2), and a comma is part of a folder’s name. When you pass folder or recursive, the SDK checks that every returned source carries folder and raises FolderScopeNotAppliedError otherwise, so a list the API did not filter is never returned as if it were (see Folders).
Python
TypeScript
from graphor import Graphorclient = Graphor()# Everything in Contracts and belowfor source in client.sources.list(folder="Contracts"): print(f"{source.folder}/{source.file_name}")# Only the sources directly in Contracts/2026direct = client.sources.list(folder="Contracts/2026", recursive=False)# Only the sources at the top leveltop_level = client.sources.list(folder="")
import Graphor from 'graphor';const client = new Graphor();// Everything in Contracts and belowfor (const source of await client.sources.list({ folder: 'Contracts' })) { console.log(`${source.folder}/${source.file_name}`);}// Only the sources directly in Contracts/2026const direct = await client.sources.list({ folder: 'Contracts/2026', recursive: false });// Only the sources at the top levelconst topLevel = await client.sources.list({ folder: '' });
Filter by status
Python
TypeScript
from graphor import Graphorclient = Graphor()sources = client.sources.list()# Filter by statuscompleted = [s for s in sources if s.status == "Completed"]processing = [s for s in sources if s.status == "Processing"]failed = [s for s in sources if s.status == "Failed"]new = [s for s in sources if s.status == "New"]print(f"Completed: {len(completed)}")print(f"Processing: {len(processing)}")print(f"Failed: {len(failed)}")print(f"New: {len(new)}")
from graphor import Graphorclient = Graphor()sources = client.sources.list()# Filter by file typepdf_files = [s for s in sources if s.file_type == "pdf"]docx_files = [s for s in sources if s.file_type == "docx"]images = [s for s in sources if s.file_type in ("png", "jpg", "jpeg")]print(f"PDFs: {len(pdf_files)}")print(f"Word docs: {len(docx_files)}")print(f"Images: {len(images)}")# List all PDF filesfor pdf in pdf_files: size_mb = pdf.file_size / (1024 * 1024) print(f" {pdf.file_name} ({size_mb:.2f} MB)")
import Graphor from 'graphor';const client = new Graphor();const sources = await client.sources.list();// Filter by file typeconst pdfFiles = sources.filter((s) => s.file_type === 'pdf');const docxFiles = sources.filter((s) => s.file_type === 'docx');const images = sources.filter((s) => ['png', 'jpg', 'jpeg'].includes(s.file_type));console.log(`PDFs: ${pdfFiles.length}`);console.log(`Word docs: ${docxFiles.length}`);console.log(`Images: ${images.length}`);// List all PDF filesfor (const pdf of pdfFiles) { const sizeMb = pdf.file_size / (1024 * 1024); console.log(` ${pdf.file_name} (${sizeMb.toFixed(2)} MB)`);}
Filter by Source Type
Python
TypeScript
from graphor import Graphorclient = Graphor()sources = client.sources.list()# Filter by source typelocal_files = [s for s in sources if s.file_source == "local file"]url_sources = [s for s in sources if s.file_source == "url"]github_sources = [s for s in sources if s.file_source == "github"]youtube_sources = [s for s in sources if s.file_source == "youtube"]print(f"Local files: {len(local_files)}")print(f"URL sources: {len(url_sources)}")print(f"GitHub repos: {len(github_sources)}")print(f"YouTube videos: {len(youtube_sources)}")
from graphor import Graphorclient = Graphor()def monitor_processing_status(): """Monitor and report on processing status.""" sources = client.sources.list() processing = [s for s in sources if s.status == "Processing"] failed = [s for s in sources if s.status == "Failed"] completed = [s for s in sources if s.status == "Completed"] new = [s for s in sources if s.status == "New"] print("=" * 50) print("Processing Status Report") print("=" * 50) print(f"Completed: {len(completed)}") print(f"Processing: {len(processing)}") print(f"New: {len(new)}") print(f"Failed: {len(failed)}") print("=" * 50) # List files currently processing if processing: print("\nCurrently Processing:") for source in processing: print(f" - {source.file_name} ({source.method})") # List failed files that need attention if failed: print("\nFailed Files (need attention):") for source in failed: print(f" - {source.file_name}: {source.message}") return { "completed": completed, "processing": processing, "new": new, "failed": failed }# Usagestatus = monitor_processing_status()
import Graphor from 'graphor';const client = new Graphor();async function monitorProcessingStatus() { const sources = await client.sources.list(); const processing = sources.filter((s) => s.status === 'Processing'); const failed = sources.filter((s) => s.status === 'Failed'); const completed = sources.filter((s) => s.status === 'Completed'); const newSources = sources.filter((s) => s.status === 'New'); console.log('='.repeat(50)); console.log('Processing Status Report'); console.log('='.repeat(50)); console.log(`Completed: ${completed.length}`); console.log(`Processing: ${processing.length}`); console.log(`New: ${newSources.length}`); console.log(`Failed: ${failed.length}`); console.log('='.repeat(50)); // List files currently processing if (processing.length > 0) { console.log('\nCurrently Processing:'); for (const source of processing) { console.log(` - ${source.file_name} (${source.method})`); } } // List failed files that need attention if (failed.length > 0) { console.log('\nFailed Files (need attention):'); for (const source of failed) { console.log(` - ${source.file_name}: ${source.message}`); } } return { completed, processing, new: newSources, failed };}// Usageconst status = await monitorProcessingStatus();
Find Source by Name
Search for a specific source by filename:
Python
TypeScript
from graphor import Graphorclient = Graphor()def find_source(file_name: str): """Find a source by exact file name.""" sources = client.sources.list() for source in sources: if source.file_name == file_name: return source return Nonedef search_sources(query: str): """Search sources by partial name match.""" sources = client.sources.list() matches = [s for s in sources if query.lower() in s.file_name.lower()] return matches# Usage# Find exact matchsource = find_source("document.pdf")if source: print(f"Found: {source.file_name} - {source.status}")else: print("Source not found")# Search by partial namematches = search_sources("report")print(f"Found {len(matches)} sources matching 'report'")for match in matches: print(f" - {match.file_name}")
import Graphor from 'graphor';const client = new Graphor();async function findSource(fileName: string) { const sources = await client.sources.list(); return sources.find((s) => s.file_name === fileName) ?? null;}async function searchSources(query: string) { const sources = await client.sources.list(); return sources.filter((s) => s.file_name.toLowerCase().includes(query.toLowerCase()));}// Usage// Find exact matchconst source = await findSource('document.pdf');if (source) { console.log(`Found: ${source.file_name} - ${source.status}`);} else { console.log('Source not found');}// Search by partial nameconst matches = await searchSources('report');console.log(`Found ${matches.length} sources matching 'report'`);for (const match of matches) { console.log(` - ${match.file_name}`);}
Project Health Check
Perform a comprehensive health check of your project:
Python
TypeScript
from graphor import Graphorfrom datetime import datetimeimport graphorclient = Graphor()def project_health_check(): """Perform a comprehensive health check of the project.""" try: sources = client.sources.list() health_report = { "timestamp": datetime.now().isoformat(), "total_sources": len(sources), "status_summary": {}, "issues": [], "recommendations": [] } # Analyze status distribution for source in sources: status = source.status or "unknown" health_report["status_summary"][status] = health_report["status_summary"].get(status, 0) + 1 # Identify issues if source.status == "Failed": health_report["issues"].append(f"Failed processing: {source.file_name}") elif source.status == "unknown": health_report["issues"].append(f"Unknown status: {source.file_name}") # Generate recommendations failed_count = health_report["status_summary"].get("Failed", 0) if failed_count > 0: health_report["recommendations"].append( f"Reprocess {failed_count} failed documents using client.sources.reprocess(file_id)" ) processing_count = health_report["status_summary"].get("Processing", 0) if processing_count > 5: health_report["recommendations"].append( "Monitor processing queue - high volume detected" ) new_count = health_report["status_summary"].get("New", 0) if new_count > 0: health_report["recommendations"].append( f"{new_count} documents awaiting processing" ) return health_report except graphor.APIStatusError as e: return { "error": str(e), "timestamp": datetime.now().isoformat() }# Usagehealth = project_health_check()print(f"Project Health Report")print(f"Timestamp: {health['timestamp']}")print(f"Total Sources: {health['total_sources']}")print(f"Status Summary: {health['status_summary']}")if health.get("issues"): print(f"\nIssues:") for issue in health["issues"]: print(f" - {issue}")if health.get("recommendations"): print(f"\nRecommendations:") for rec in health["recommendations"]: print(f" - {rec}")
import Graphor from 'graphor';const client = new Graphor();async function projectHealthCheck() { try { const sources = await client.sources.list(); const statusSummary: Record<string, number> = {}; const issues: string[] = []; const recommendations: string[] = []; // Analyze status distribution for (const source of sources) { const status = source.status || 'unknown'; statusSummary[status] = (statusSummary[status] ?? 0) + 1; if (source.status === 'Failed') { issues.push(`Failed processing: ${source.file_name}`); } else if (source.status === 'unknown') { issues.push(`Unknown status: ${source.file_name}`); } } // Generate recommendations const failedCount = statusSummary['Failed'] ?? 0; if (failedCount > 0) { recommendations.push( `Reprocess ${failedCount} failed documents using client.sources.reprocess(file_id)`, ); } const processingCount = statusSummary['Processing'] ?? 0; if (processingCount > 5) { recommendations.push('Monitor processing queue - high volume detected'); } const newCount = statusSummary['New'] ?? 0; if (newCount > 0) { recommendations.push(`${newCount} documents awaiting processing`); } return { timestamp: new Date().toISOString(), totalSources: sources.length, statusSummary, issues, recommendations, }; } catch (err) { return { error: err instanceof Graphor.APIError ? err.message : String(err), timestamp: new Date().toISOString(), }; }}// Usageconst health = await projectHealthCheck();console.log('Project Health Report');console.log(`Timestamp: ${health.timestamp}`);if ('totalSources' in health) { console.log(`Total Sources: ${health.totalSources}`); console.log('Status Summary:', health.statusSummary); if (health.issues?.length) { console.log('\nIssues:'); for (const issue of health.issues) { console.log(` - ${issue}`); } } if (health.recommendations?.length) { console.log('\nRecommendations:'); for (const rec of health.recommendations) { console.log(` - ${rec}`); } }}
Async Batch Operations
Use the list to perform batch operations efficiently:
Python
TypeScript
import asynciofrom graphor import AsyncGraphorimport graphorasync def reprocess_failed_sources(method: str = "balanced"): """Find and reprocess all failed sources.""" client = AsyncGraphor(timeout=300.0) # Get all sources sources = await client.sources.list() # Find failed sources failed = [s for s in sources if s.status == "Failed"] if not failed: print("No failed sources to reprocess") return [] print(f"Found {len(failed)} failed sources to reprocess") # Reprocess each failed source (returns build_id; poll get_build_status to wait) results = [] for source in failed: try: print(f"Reprocessing: {source.file_name} ({source.file_id})...") build_id = await client.sources.reprocess( file_id=source.file_id, partition_method=method ) results.append({"file_id": source.file_id, "build_id": build_id, "status": "scheduled"}) print(f" OK - build_id: {build_id}") except graphor.APIStatusError as e: results.append({"file_id": source.file_id, "status": "failed", "error": str(e)}) print(f" FAIL - {source.file_id}: {e}") return results# Usageresults = asyncio.run(reprocess_failed_sources("balanced"))
from graphor import Graphorimport graphorfrom dataclasses import dataclassfrom typing import Optional@dataclassclass SourceSummary: total: int completed: int processing: int failed: int new: int total_size_mb: floatclass SourceManager: def __init__(self, api_key: Optional[str] = None): self.client = Graphor(api_key=api_key) if api_key else Graphor() self._cache = None def refresh(self): """Refresh the sources cache.""" self._cache = self.client.sources.list() return self._cache @property def sources(self): """Get sources (cached).""" if self._cache is None: self.refresh() return self._cache def get_summary(self) -> SourceSummary: """Get a summary of all sources.""" sources = self.sources total_size = sum(s.file_size for s in sources) return SourceSummary( total=len(sources), completed=len([s for s in sources if s.status == "Completed"]), processing=len([s for s in sources if s.status == "Processing"]), failed=len([s for s in sources if s.status == "Failed"]), new=len([s for s in sources if s.status == "New"]), total_size_mb=round(total_size / (1024 * 1024), 2) ) def find_by_name(self, name: str): """Find a source by exact name.""" for source in self.sources: if source.file_name == name: return source return None def search(self, query: str): """Search sources by partial name match.""" return [s for s in self.sources if query.lower() in s.file_name.lower()] def filter_by_status(self, status: str): """Filter sources by status.""" return [s for s in self.sources if s.status == status] def filter_by_type(self, file_type: str): """Filter sources by file type.""" return [s for s in self.sources if s.file_type == file_type] def get_failed(self): """Get all failed sources.""" return self.filter_by_status("Failed") def get_processing(self): """Get all processing sources.""" return self.filter_by_status("Processing")# Usagemanager = SourceManager()# Get summarysummary = manager.get_summary()print(f"Total: {summary.total}, Completed: {summary.completed}, Failed: {summary.failed}")# Find a specific sourcesource = manager.find_by_name("document.pdf")if source: print(f"Found: {source.file_name} - {source.status}")# Search sourcesmatches = manager.search("report")print(f"Found {len(matches)} matches for 'report'")# Get failed sourcesfailed = manager.get_failed()print(f"Failed sources: {len(failed)}")
import timefrom graphor import Graphorimport graphorclient = Graphor()def continuous_monitoring(interval_seconds: int = 60, max_iterations: int = None): """Continuously monitor source processing status.""" iteration = 0 while max_iterations is None or iteration < max_iterations: try: sources = client.sources.list() processing = len([s for s in sources if s.status == "Processing"]) failed = len([s for s in sources if s.status == "Failed"]) completed = len([s for s in sources if s.status == "Completed"]) print(f"[{time.strftime('%H:%M:%S')}] " f"Completed: {completed} | Processing: {processing} | Failed: {failed}") # Alert if new failures detected if failed > 0: failed_sources = [s for s in sources if s.status == "Failed"] print(f" Warning - Failed sources: {[s.file_name for s in failed_sources]}") time.sleep(interval_seconds) iteration += 1 except graphor.APIConnectionError as e: print(f"[{time.strftime('%H:%M:%S')}] Connection error: {e}") time.sleep(interval_seconds) except KeyboardInterrupt: print("\nMonitoring stopped") break# Usage (monitor every 30 seconds, 10 times)# continuous_monitoring(interval_seconds=30, max_iterations=10)
import Graphor from 'graphor';const client = new Graphor();async function continuousMonitoring(intervalSeconds = 60, maxIterations?: number) { let iteration = 0; while (maxIterations === undefined || iteration < maxIterations) { try { const sources = await client.sources.list(); const processing = sources.filter((s) => s.status === 'Processing').length; const failed = sources.filter((s) => s.status === 'Failed').length; const completed = sources.filter((s) => s.status === 'Completed').length; const time = new Date().toLocaleTimeString(); console.log( `[${time}] Completed: ${completed} | Processing: ${processing} | Failed: ${failed}`, ); // Alert if new failures detected if (failed > 0) { const failedSources = sources.filter((s) => s.status === 'Failed'); console.log( ` Warning - Failed sources: ${failedSources.map((s) => s.file_name).join(', ')}`, ); } await new Promise((r) => setTimeout(r, intervalSeconds * 1000)); iteration++; } catch (err) { if (err instanceof Graphor.APIConnectionError) { const time = new Date().toLocaleTimeString(); console.log(`[${time}] Connection error: ${err.message}`); await new Promise((r) => setTimeout(r, intervalSeconds * 1000)); } else { throw err; } } }}// Usage (monitor every 30 seconds, 10 times)// await continuousMonitoring(30, 10);
Error Reference
Error Type
Status Code
Description
AuthenticationError
401
Invalid or missing API key
PermissionDeniedError
403
Access denied to the specified project
UnprocessableEntityError
422
Invalid folder path (code: "request.invalid")
RateLimitError
429
Too many requests, please retry after waiting
InternalServerError
≥500
Server-side error retrieving sources
FolderScopeNotAppliedError
—
folder or recursive was passed and the API did not apply the filter
APIConnectionError
N/A
Network connectivity issues
APITimeoutError
N/A
Request timed out
Best Practices
Performance Optimization
Cache results: Store the response locally when making multiple queries
Filter client-side: The SDK returns all sources; filter in your code as needed
Use async: For applications that need to perform other work while waiting
Python
TypeScript
# Example: Cache sources for multiple operationssources = client.sources.list()# Now perform multiple filter operations without re-fetchingpdfs = [s for s in sources if s.file_type == "pdf"]completed = [s for s in sources if s.status == "Completed"]large_files = [s for s in sources if s.file_size > 10 * 1024 * 1024]