> ## 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.

# Request Logs: Advanced Queries

> Filter by trace ID, model spans, metadata, and MCP

## Advanced Use Cases

<AccordionGroup>
  <Accordion title="Filter by Specific Trace ID">
    Fetch spans of a specific traceId

    <CodeGroup>
      ```python TrueFoundry SDK lines theme={"dark"}
      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"))
      ```

      ```python HTTP API lines theme={"dark"}
      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!")
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Fetch all model spans">
    Filter spans by model spanType using the `tfy.span_type` span attribute filter with value `Model`.

    <CodeGroup>
      ```python TrueFoundry SDK lines theme={"dark"}
      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"))
      ```

      ```python HTTP API lines theme={"dark"}
      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!")
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="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.

    <CodeGroup>
      ```python TrueFoundry SDK lines theme={"dark"}
      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"))
      ```

      ```python HTTP API lines theme={"dark"}
      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!")
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="Fetch spans with MCP in span name">
    Filter spans that have `MCP` in the span name.

    <CodeGroup>
      ```python TrueFoundry SDK lines theme={"dark"}
      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"))
      ```

      ```python HTTP API lines theme={"dark"}
      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!")
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="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.

    <CodeGroup>
      ```python TrueFoundry SDK lines theme={"dark"}
      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"))
      ```

      ```python HTTP API lines theme={"dark"}
      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!")
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>