How to beginner · 3 min read

How to filter traces in LangSmith

Q: How to filter traces in LangSmith

Use the LangSmith Python SDK's Client to query traces with filters by specifying parameters like filter or query in the client.traces.list() method. Filters support fields such as status, tags, and time range to narrow down trace results efficiently.

Quick answer

Use the LangSmith Python SDK's Client to query traces with filters by specifying parameters like filter or query in the client.traces.list() method. Filters support fields such as status, tags, and time range to narrow down trace results efficiently.

PREREQUISITES

Python 3.8+
pip install langsmith
LangSmith API key set as LANGSMITH_API_KEY environment variable

Setup

Install the LangSmith Python SDK and set your API key as an environment variable for authentication.

bash

pip install langsmith

Step by step

This example demonstrates how to filter traces by status and tags using the LangSmith Python SDK.

python

import os
from langsmith import Client

# Initialize LangSmith client with API key from environment
client = Client(api_key=os.environ["LANGSMITH_API_KEY"])

# Define filter parameters
filter_params = {
    "status": "completed",  # Filter traces with status 'completed'
    "tags": ["project:myproject", "env:production"]  # Filter traces with these tags
}

# List traces with filters
traces = client.traces.list(filter=filter_params, limit=10)

# Print trace IDs and statuses
for trace in traces:
    print(f"Trace ID: {trace.id}, Status: {trace.status}")

output

Trace ID: 123abc, Status: completed
Trace ID: 456def, Status: completed
Trace ID: 789ghi, Status: completed

Common variations

You can filter traces by time range, user ID, or search query. The filter parameter accepts multiple fields, and you can combine them for precise trace retrieval.

Example filtering by time range:

python

from datetime import datetime, timedelta

# Filter traces from last 7 days
seven_days_ago = datetime.utcnow() - timedelta(days=7)
filter_params = {
    "start_time": seven_days_ago.isoformat() + "Z",
    "status": "completed"
}

traces = client.traces.list(filter=filter_params, limit=5)
for trace in traces:
    print(f"Trace ID: {trace.id}, Timestamp: {trace.created_at}")

output

Trace ID: 234bcd, Timestamp: 2026-04-15T12:34:56Z
Trace ID: 567efg, Timestamp: 2026-04-14T09:21:30Z

Troubleshooting

If no traces are returned, verify your filter criteria match existing traces.
Ensure your LANGSMITH_API_KEY environment variable is set correctly.
Check network connectivity and LangSmith service status if API calls fail.

✅

Key Takeaways

Use the LangSmith Python SDK's client.traces.list() with filter to query traces efficiently.
Combine filters like status, tags, and time range for precise trace retrieval.
Always set your API key in the LANGSMITH_API_KEY environment variable for authentication.

Verified 2026-04

Verify ↗