How to list traces with metadata filter via API or SDK #9479
-
|
Hi team, I’m trying to fetch a list of traces from Langfuse with a filter on a specific metadata field. My goal is to only retrieve traces where a given key and value exist in the metadata object (for example, Questions:
I’ve found examples for metrics queries, but not for listing actual traces. Any guidance or example code would be really helpful! Thanks in advance! |
Beta Was this translation helpful? Give feedback.
Replies: 2 comments 6 replies
-
|
Based on the available documentation, I can provide information about listing traces via API and SDK, though direct metadata filtering capabilities are limited. Available Query ParametersThe GET
SDK Usage ExamplesYou can list traces using the Python SDK like this (2): from langfuse import get_client
langfuse = get_client()
# Get the last 50 traces
traces = langfuse.api.trace.list(limit=50)
# Filter by specific user
traces = langfuse.api.trace.list(user_id="u-svQKrql")
# Pagination example
all_traces = []
limit = 50
page = 1
while True:
traces = langfuse.api.trace.list(limit=limit, page=page)
all_traces.extend(traces.data)
if len(traces.data) < limit or len(all_traces) >= 1000:
break
page += 1Metadata Filtering LimitationsUnfortunately, direct metadata filtering is not supported in the traces API (1). As noted in the GitHub discussions, this limitation exists because the API doesn't currently support filtering traces by custom metadata fields (3). Workarounds
OpenTelemetry Metadata ConsiderationsFor OpenTelemetry traces, metadata filtering can be particularly challenging due to the nested structure of attributes. Langfuse only supports filtering on top-level metadata keys, and OpenTelemetry attributes are typically nested under If you need to make specific OpenTelemetry attributes filterable, you can use the with tracer.start_as_current_span("Langfuse Attributes") as span:
span.set_attribute("langfuse.trace.metadata.user_name", "user-123")For more complex filtering needs, you may need to use the Metrics API or implement client-side filtering after retrieving the traces. 📚 Sources:
Have another question? Just tag @inkeep. |
Beta Was this translation helpful? Give feedback.
-
|
Since this is already supported in the platform, could we consider enabling it in the API too? or any workaround for the same? |
Beta Was this translation helpful? Give feedback.
-
|
Hi @devinder-augur, we have this on our roadmap here: https://github.com/orgs/langfuse/discussions/3276. Feel free to subscribe to this post to get updates on this and add any additional thoughts you might have. |
Beta Was this translation helpful? Give feedback.
-
|
Thanks for pointing me to the right discussion, @jannikmaierhoefer , but it seems like a stale issue since I don’t see any updates on that thread. |
Beta Was this translation helpful? Give feedback.
-
|
Hi @devinder-augur, querying traces via API or SDK now allows filtering for metadata: https://langfuse.com/changelog/2025-10-10-advanced-filtering-public-traces-api |
Beta Was this translation helpful? Give feedback.
-
|
@jannikmaierhoefer Any chance you can provide an example for how to filter on metadata via python's But still struggling to get this filter working: [
{
"type": "stringObject",
"column": "metadata",
"key": "scope",
"operator": "contains",
"value": "langfuse-sdk"
}
] The same code I am using, but with a different filter does work: [
{
"type": "number",
"column": "totalTokens",
"operator": ">",
"value": "0"
}
] So I just can't figure out metadata filtering. |
Beta Was this translation helpful? Give feedback.
-
|
@devinder-augur, could you please try the following: import json
import os
import requests
from requests.auth import HTTPBasicAuth
BASE_URL = os.getenv("LANGFUSE_BASE_URL", "https://cloud.langfuse.com")
PUBLIC_KEY = os.environ["LANGFUSE_PUBLIC_KEY"]
SECRET_KEY = os.environ["LANGFUSE_SECRET_KEY"]
filters = [
{
"type": "stringObject",
"column": "metadata",
"key": "use_case",
"operator": "=",
"value": "retrieval-augmented",
},
{
"type": "number",
"column": "latency",
"operator": "<=",
"value": 5,
},
]
response = requests.get(
f"{BASE_URL}/api/public/observations",
params={
"limit": 50,
"page": 1,
"filter": json.dumps(filters),
},
auth=HTTPBasicAuth(PUBLIC_KEY, SECRET_KEY),
headers={
"X-Langfuse-Public-Key": PUBLIC_KEY,
"X-Langfuse-Sdk-Name": "python-custom",
"X-Langfuse-Sdk-Version": "1.0.0",
},
timeout=10,
)
response.raise_for_status()
payload = response.json()
for obs in payload["data"]:
print(obs["id"], obs["metadata"].get("use_case"), obs["latency"]) |
Beta Was this translation helpful? Give feedback.
-
|
This does not work for me, I'm unable to get traces that have the following metadata: import json
import os
import requests
from requests.auth import HTTPBasicAuth
BASE_URL = os.getenv("LANGFUSE_BASE_URL", "https://langfuse.example.com")
PUBLIC_KEY = os.environ["LANGFUSE_PUBLIC_KEY"]
SECRET_KEY = os.environ["LANGFUSE_SECRET_KEY"]
filters = [
{
"type": "stringObject",
"column": "metadata",
"key": "scope",
"operator": "=",
"value": "langfuse-sdk",
},
]
response = requests.get(
f"{BASE_URL}/api/public/traces",
params={
"limit": 50,
"page": 1,
"filter": json.dumps(filters),
},
auth=HTTPBasicAuth(PUBLIC_KEY, SECRET_KEY),
headers={
"X-Langfuse-Public-Key": PUBLIC_KEY,
"X-Langfuse-Sdk-Name": "python-custom",
"X-Langfuse-Sdk-Version": "1.0.0",
},
timeout=10,
)
response.raise_for_status()
payload = response.json()
for obs in payload["data"]:
print(obs["id"], obs["metadata"].get("scope"))For context, we have OTEL traces leaking into langfuse and we are trying to filter for traces that are coming from langfuse (not our OTEL auto instrumentation). |
Beta Was this translation helpful? Give feedback.
Hi @devinder-augur, querying traces via API or SDK now allows filtering for metadata: https://langfuse.com/changelog/2025-10-10-advanced-filtering-public-traces-api