Skip to main content

Documentation Index

Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Advanced Use Cases

Fetch spans of a specific traceId
from truefoundry import client
from truefoundry_sdk import SortDirection

spans = client.traces.query_spans(
    data_routing_destination="default",
    start_time="2025-10-08T00:00:00.000Z",
    end_time="2025-10-08T23:59:59.999Z",
    trace_ids=[
        "0199c25e124a70989b0455584fbbf7b7"
    ],
    limit=200,
    sort_direction=SortDirection.DESC
)

# Process all spans across all pages
for span in spans:
    print(span.span_name, span.duration, span.span_attributes.get("tfy.span_type"))
Filter spans by model spanType using the tfy.span_type span attribute filter with value Model.
from truefoundry import client
from truefoundry_sdk import SortDirection, SpanAttributeFilter
from truefoundry_sdk.types.span_attribute_filter_operator import SpanAttributeFilterOperator

spans = client.traces.query_spans(
    data_routing_destination="default",
    start_time="2025-10-08T00:00:00.000Z",
    end_time="2025-10-08T23:59:59.999Z",
    filters=[
        SpanAttributeFilter(span_attribute_key="tfy.span_type", operator=SpanAttributeFilterOperator.EQUAL, value="Model"),
    ],
    limit=200,
    sort_direction=SortDirection.DESC
)

# Process all spans across all pages
for span in spans:
    print(span.span_name, span.span_attributes.get("tfy.span_type"))
Filter spans based on custom metadata keys and values that were passed to Gateway requests using the X-TFY-METADATA header.
from truefoundry import client
from truefoundry_sdk import SortDirection, GatewayRequestMetadataFilter
from truefoundry_sdk.types.gateway_request_metadata_filter_operator import GatewayRequestMetadataFilterOperator

spans = client.traces.query_spans(
    data_routing_destination="default",
    start_time="2025-10-08T00:00:00.000Z",
    end_time="2025-10-08T23:59:59.999Z",
    filters=[
        GatewayRequestMetadataFilter(gateway_request_metadata_key="application", operator=GatewayRequestMetadataFilterOperator.EQUAL, value="booking-bot"),
        GatewayRequestMetadataFilter(gateway_request_metadata_key="environment", operator=GatewayRequestMetadataFilterOperator.IN, value=["staging", "production"]),
    ],
    limit=200,
    sort_direction=SortDirection.DESC
)

# Process all spans across all pages
for span in spans:
    print(span.span_name, span.span_attributes.get("tfy.span_type"))
Filter spans that have MCP in the span name.
from truefoundry import client
from truefoundry_sdk import SortDirection, SpanFieldFilter
from truefoundry_sdk.types.span_field_filter_span_field_name import SpanFieldFilterSpanFieldName
from truefoundry_sdk.types.span_field_filter_operator import SpanFieldFilterOperator

spans = client.traces.query_spans(
    data_routing_destination="default",
    start_time="2025-10-08T00:00:00.000Z",
    end_time="2025-10-08T23:59:59.999Z",
    filters=[
        SpanFieldFilter(span_field_name=SpanFieldFilterSpanFieldName.SPAN_NAME, operator=SpanFieldFilterOperator.STRING_CONTAINS, value="MCP"),
    ],
    limit=200,
    sort_direction=SortDirection.DESC
)

# Process all spans across all pages
for span in spans:
    print(span.span_name, span.span_attributes.get("tfy.span_type"))
Fetch model spans by filtering with tfy.span_type span attribute filter with value Model, and then further filter by model name using the tfy.model.name span attribute filter.
from truefoundry import client
from truefoundry_sdk import SortDirection, SpanAttributeFilter
from truefoundry_sdk.types.span_attribute_filter_operator import SpanAttributeFilterOperator

spans = client.traces.query_spans(
    data_routing_destination="default",
    start_time="2025-10-08T00:00:00.000Z",
    end_time="2025-10-08T23:59:59.999Z",
    filters=[
        SpanAttributeFilter(span_attribute_key="tfy.model.name", operator=SpanAttributeFilterOperator.EQUAL, value="openai-main/gpt-4"),
        SpanAttributeFilter(span_attribute_key="tfy.span_type", operator=SpanAttributeFilterOperator.EQUAL, value="Model"),
    ],
    limit=200,
    sort_direction=SortDirection.DESC
)

# Process all spans across all pages
for span in spans:
    print(span.span_name, span.span_attributes.get("tfy.model.name"))