# list_runs

> **Method** in `langsmith`

📖 [View in docs](https://reference.langchain.com/python/langsmith/client/Client/list_runs)

List runs from the LangSmith API.

.. admonition:: Deprecated

    Use :meth:`langsmith.Client.runs.query` instead.
    See https://docs.langchain.com/langsmith/smithdb-sdk-migration-query-runs#runs-query for the migration guide.
    Will be removed after Jan 31, 2027.

## Signature

```python
list_runs(
    self,
    *,
    project_id: Optional[Union[ID_TYPE, Sequence[ID_TYPE]]] = None,
    project_name: Optional[Union[str, Sequence[str]]] = None,
    run_type: Optional[str] = None,
    trace_id: Optional[ID_TYPE] = None,
    reference_example_id: Optional[ID_TYPE] = None,
    query: Optional[str] = None,
    filter: Optional[str] = None,
    trace_filter: Optional[str] = None,
    tree_filter: Optional[str] = None,
    is_root: Optional[bool] = None,
    parent_run_id: Optional[ID_TYPE] = None,
    start_time: Optional[datetime.datetime] = None,
    error: Optional[bool] = None,
    run_ids: Optional[Sequence[ID_TYPE]] = None,
    select: Optional[Sequence[str]] = None,
    limit: Optional[int] = None,
    **kwargs: Any = {},
) -> Iterator[ls_schemas.Run]
```

## Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `project_id` | `Optional[Union[ID_TYPE, Sequence[ID_TYPE]]]` | No | The ID(s) of the project to filter by. (default: `None`) |
| `project_name` | `Optional[Union[str, Sequence[str]]]` | No | The name(s) of the project to filter by. (default: `None`) |
| `run_type` | `Optional[str]` | No | The type of the runs to filter by. (default: `None`) |
| `trace_id` | `Optional[ID_TYPE]` | No | The ID of the trace to filter by. (default: `None`) |
| `reference_example_id` | `Optional[ID_TYPE]` | No | The ID of the reference example to filter by. (default: `None`) |
| `query` | `Optional[str]` | No | The query string to filter by. (default: `None`) |
| `filter` | `Optional[str]` | No | The filter string to filter by. (default: `None`) |
| `trace_filter` | `Optional[str]` | No | Filter to apply to the ROOT run in the trace tree.  This is meant to be used in conjunction with the regular `filter` parameter to let you filter runs by attributes of the root run within a trace. (default: `None`) |
| `tree_filter` | `Optional[str]` | No | Filter to apply to OTHER runs in the trace tree, including sibling and child runs.  This is meant to be used in conjunction with the regular `filter` parameter to let you filter runs by attributes of any run within a trace. (default: `None`) |
| `is_root` | `Optional[bool]` | No | Whether to filter by root runs. (default: `None`) |
| `parent_run_id` | `Optional[ID_TYPE]` | No | The ID of the parent run to filter by. (default: `None`) |
| `start_time` | `Optional[datetime.datetime]` | No | The start time to filter by. (default: `None`) |
| `error` | `Optional[bool]` | No | Whether to filter by error status. (default: `None`) |
| `run_ids` | `Optional[Sequence[ID_TYPE]]` | No | The IDs of the runs to filter by. (default: `None`) |
| `select` | `Optional[Sequence[str]]` | No | The fields to select. (default: `None`) |
| `limit` | `Optional[int]` | No | The maximum number of runs to return. (default: `None`) |
| `**kwargs` | `Any` | No | Additional keyword arguments. (default: `{}`) |

## ⚠️ Deprecated

list_runs() is deprecated and will be removed after Jan 31, 2027. Use client.runs.query() instead. See https://docs.langchain.com/langsmith/smithdb-sdk-migration#runs-query for the migration guide.

---

[View source on GitHub](https://github.com/langchain-ai/langsmith-sdk/blob/aadfe00ed2cf31808d14a32646e73030a9eeb0b5/python/langsmith/client.py#L4360)