Skip to main content
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

client.sources.list()

Method signature

Parameters

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:

Status values

Backend returns status with capital letters. Typical values:

File Source Types

Code Examples

Basic Usage

Async Usage

Filter by file_ids

Filter by folder

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).

Filter by status

Filter by File Type

Filter by Source Type

Error Handling

Advanced Examples

Source Analysis

Analyze your project’s sources with detailed statistics:

Status Monitoring

Monitor the processing status of your documents:

Find Source by Name

Search for a specific source by filename:

Project Health Check

Perform a comprehensive health check of your project:

Async Batch Operations

Use the list to perform batch operations efficiently:

Source Management Class

A complete class for managing sources:

Continuous Monitoring

Set up continuous monitoring of your sources:

Error Reference

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

Data Management

  • Track processing times: Monitor how long documents take to process
  • Identify patterns: Look for file types or sizes that frequently fail
  • Plan capacity: Use file counts and sizes for storage planning

Error Handling

  • Implement retries: Handle temporary network issues with the SDK’s built-in retry mechanism
  • Monitor status: Regularly check for failed processing jobs
  • Graceful degradation: Have fallback plans when the API is unavailable

Troubleshooting

Causes: Large number of sources, server load, or network issuesSolutions:
  • Implement request timeouts
  • Use response caching for non-critical applications
  • Consider filtering client-side after initial fetch
Causes: No sources in project, wrong API key, or permission issuesSolutions:
  • Verify you have uploaded documents to your project
  • Check that your API key is correct and active
  • Ensure you’re accessing the right project
Causes: Processing lag, system sync issues, or database inconsistenciesSolutions:
  • Wait a few minutes and retry the request
  • Call sources.list() again to refresh the data
  • Contact support if inconsistencies persist
Causes: Invalid token, expired token, or revoked accessSolutions:
  • Verify API key format and validity
  • Check token hasn’t been revoked in dashboard
  • Generate a new API key if necessary

Next steps

After listing your sources:

Upload

Ingest new files, URLs, GitHub repos, or YouTube videos

Reprocess source

Reprocess a source with a different partition method

Get elements

Retrieve parsed elements from a source

Delete source

Remove a source by file_id

Folders

List, create, rename and delete folders; move sources