fetch_runs
Fetch and filter LangSmith run data by project, trace, type, error status, or FQL query. Automatic pagination handles large result sets.
Instructions
Fetch LangSmith runs from one or more projects with flexible filters and automatic pagination.
All results are paginated by character budget to keep responses manageable. Use page_number and total_pages from the response to iterate through multiple pages.
Args: project_name (str): The project name. For multiple projects, use JSON array string. limit (int): Max runs to fetch from LangSmith API (capped at 100). These runs are then paginated by character budget into pages. page_number (int): 1-based page index. Use with total_pages from response to iterate through pages. trace_id (str, optional): Return only runs that belong to this trace. run_type (str, optional): Filter by type: "llm", "chain", "tool", "retriever". error (str, optional): "true" for errored runs, "false" for successful. is_root (str, optional): "true" for only top-level traces. filter (str, optional): Filter Query Language (FQL) expression. trace_filter (str, optional): Filter applied to the root run. tree_filter (str, optional): Filter applied to any run in the trace tree. order_by (str, optional): Sort field; prefix with "-" for descending. Default "-start_time". reference_example_id (str, optional): Filter runs by reference example ID. max_chars_per_page (int): Max chars per page, capped at 30000. Default 25000. preview_chars (int): Truncate long strings to this length. Default 150.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | "true" for errored runs, "false" for successful | |
| limit | Yes | Maximum number of runs to fetch from LangSmith API (capped at 100) | |
| filter | No | Filter Query Language (FQL) expression | |
| is_root | No | "true" for only top-level traces | |
| order_by | No | Sort field; prefix with '-' for descending | -start_time |
| run_type | No | Filter by type: "llm", "chain", "tool", "retriever" | |
| trace_id | No | Return only runs belonging to this trace UUID | |
| page_number | No | 1-based page index | |
| tree_filter | No | Filter applied to any run in the trace tree | |
| project_name | Yes | The project name to fetch runs from | |
| trace_filter | No | Filter applied to the root run in each trace tree | |
| preview_chars | No | Truncate long strings to this length | |
| max_chars_per_page | No | Max character count per page, capped at 30000 | |
| reference_example_id | No | Filter runs by reference example ID |