Request Logs: Advanced Queries

Filter by Specific Trace ID

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"))

import requests

page_token = None
done = False

while not done:
    # Make API request
    response = requests.post(
        "https://{control_plane_url}/api/svc/v1/spans/query",
        headers={
            "Authorization": "Bearer YOUR_API_TOKEN",
            "Content-Type": "application/json"
        },
        json={
            "dataRoutingDestination": "default",
            "startTime": "2025-10-08T00:00:00.000Z",
            "endTime": "2025-10-08T23:59:59.999Z",
            "traceIds": ["0199c25e124a70989b0455584fbbf7b7"],
            "limit": 200,
            "sortDirection": "desc",
            "pageToken": page_token
        }
    )
    
    response.raise_for_status()
    data = response.json()

    for span in data['data']:
        print(span['spanName'], span['duration'], span['spanAttributes'].get("tfy.span_type"))
    
    page_token = data['pagination'].get("nextPageToken")
    done = page_token is None

print("Fetch spans by trace ID completed!")

Fetch all model spans

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"))

import requests

page_token = None
done = False

while not done:
    # Make API request
    response = requests.post(
        "https://{control_plane_url}/api/svc/v1/spans/query",
        headers={
            "Authorization": "Bearer YOUR_API_TOKEN",
            "Content-Type": "application/json"
        },
        json={
            "dataRoutingDestination": "default",
            "startTime": "2025-10-08T00:00:00.000Z",
            "endTime": "2025-10-08T23:59:59.999Z",
            "filters": [
                {"spanAttributeKey": "tfy.span_type", "operator": "EQUAL", "value": "Model"},
            ],
            "limit": 200,
            "sortDirection": "desc",
            "pageToken": page_token
        }
    )
    
    response.raise_for_status()
    data = response.json()

    for span in data['data']:
        print(span['spanName'], span['spanAttributes'].get("tfy.span_type"))
    
    page_token = data['pagination'].get("nextPageToken")
    done = page_token is None

print("Fetch spans by model spanType completed!")

Fetch requests with Gateway request metadata

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"))

import requests

page_token = None
done = False

while not done:
    # Make API request
    response = requests.post(
        "https://{control_plane_url}/api/svc/v1/spans/query",
        headers={
            "Authorization": "Bearer YOUR_API_TOKEN",
            "Content-Type": "application/json"
        },
        json={
            "dataRoutingDestination": "default",
            "startTime": "2025-10-08T00:00:00.000Z",
            "endTime": "2025-10-08T23:59:59.999Z",
            "filters": [
                {"gatewayRequestMetadataKey": "application", "operator": "EQUAL", "value": "booking-bot"},
                {"gatewayRequestMetadataKey": "environment", "operator": "IN", "value": ["staging", "production"]},
            ],
            "limit": 200,
            "sortDirection": "desc",
            "pageToken": page_token
        }
    )
    
    response.raise_for_status()
    data = response.json()

    for span in data['data']:
        print(span['spanName'], span['spanAttributes'].get("tfy.span_type"))
    
    page_token = data['pagination'].get("nextPageToken")
    done = page_token is None

print("Fetch spans with Gateway request metadata completed!")

Fetch spans with MCP in span name

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"))

import requests

page_token = None
done = False

while not done:
    # Make API request
    response = requests.post(
        "https://{control_plane_url}/api/svc/v1/spans/query",
        headers={
            "Authorization": "Bearer YOUR_API_TOKEN",
            "Content-Type": "application/json"
        },
        json={
            "dataRoutingDestination": "default",
            "startTime": "2025-10-08T00:00:00.000Z",
            "endTime": "2025-10-08T23:59:59.999Z",
            "filters": [
                {"spanFieldName": "spanName", "operator": "STRING_CONTAINS", "value": "MCP"},
            ],
            "limit": 200,
            "sortDirection": "desc",
            "pageToken": page_token
        }
    )
    
    response.raise_for_status()
    data = response.json()

    for span in data['data']:
        print(span['spanName'], span['spanAttributes'].get("tfy.span_type"))
    
    page_token = data['pagination'].get("nextPageToken")
    done = page_token is None

print("Fetch MCP spans completed!")

Filter model spans by model name

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"))

import requests

page_token = None
done = False

while not done:
    # Make API request
    response = requests.post(
        "https://{control_plane_url}/api/svc/v1/spans/query",
        headers={
            "Authorization": "Bearer YOUR_API_TOKEN",
            "Content-Type": "application/json"
        },
        json={
            "dataRoutingDestination": "default",
            "startTime": "2025-10-08T00:00:00.000Z",
            "endTime": "2025-10-08T23:59:59.999Z",
            "filters": [
                {"spanAttributeKey": "tfy.model.name", "operator": "EQUAL", "value": "openai-main/gpt-4"},
                {"spanAttributeKey": "tfy.span_type", "operator": "EQUAL", "value": "Model"},
            ],
            "limit": 200,
            "sortDirection": "desc",
            "pageToken": page_token
        }
    )
    
    response.raise_for_status()
    data = response.json()

    for span in data['data']:
        print(span['spanName'], span['spanAttributes'].get("tfy.model.name"))
    
    page_token = data['pagination'].get("nextPageToken")
    done = page_token is None

print("Fetch spans by model name completed!")

Get Started

LLM Gateway

MCP Registry and Gateway

Skills Registry

Prompt Registry

Guardrails and Security

Observability

Deployment

Admin Guide

Chat

Messages

Embeddings

Rerank

Responses

Image

Audio

Batch

Files

Fine-tuning

Moderations

Models

Request Logs: Advanced Queries

Advanced Use Cases

​Advanced Use Cases

Advanced Use Cases