> ## 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: Filtering

> Filter Gateway request logs by time, user, trace ID, and more

## Filter Request Logs

While fetching all Gateway request logs is useful for general monitoring,
you'll often want to filter logs based on specific criteria such as user identity, model names, etc.
You can achieve this using the `filters` parameter in the `query_spans` method.

The API supports the following common filter types:

* **Span fields filtering**: Filter logs by span fields such as `spanName`, `traceId`, `spanId`, etc. See the [Query Spans documentation](/docs/truefoundry_sdk/traces#query-spans) to understand the supported options for `spanFieldName` and `operator`.
* **Span attributes filtering**: Filter logs by span attributes, e.g., using `tfy.model.name` for model name. See [Span attributes](/docs/ai-gateway/fetch-request-logs-span-attributes) section to understand the supported options for `spanAttributeKey`
* **Gateway request metadata filtering**: Filter logs based on [Custom Metadata](/docs/ai-gateway/log-custom-metadata) keys and values that you passed to Gateway requests.

The following example demonstrates how to retrieve request logs for OpenAI models submitted by a specific user, where custom metadata matches certain values:

<CodeGroup>
  ```python TrueFoundry SDK lines theme={"dark"}
  from truefoundry import client
  from truefoundry_sdk import SpanFieldFilter, SpanAttributeFilter, GatewayRequestMetadataFilter
  from truefoundry_sdk.types.span_field_filter_span_field_name import SpanFieldFilterSpanFieldName
  from truefoundry_sdk.types.span_field_filter_operator import SpanFieldFilterOperator
  from truefoundry_sdk.types.span_attribute_filter_operator import SpanAttributeFilterOperator
  from truefoundry_sdk.types.gateway_request_metadata_filter_operator import GatewayRequestMetadataFilterOperator

  # Fetch LLM Gateway request logs with filters
  spans = client.traces.query_spans(
      data_routing_destination="default",
      start_time="2025-01-21T00:00:00.000Z",
      filters=[
          SpanFieldFilter(span_field_name=SpanFieldFilterSpanFieldName.CREATED_BY_SUBJECT_SLUG, operator=SpanFieldFilterOperator.EQUAL, value="user@example.com"),
          SpanAttributeFilter(span_attribute_key="tfy.model.name", operator=SpanAttributeFilterOperator.STRING_CONTAINS, value="openai"),
          GatewayRequestMetadataFilter(gateway_request_metadata_key="foo", operator=GatewayRequestMetadataFilterOperator.IN, value=["bar1", "bar2"]),
      ]
  )

  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-08T20:16:54",
              "filters": [
                  {"spanFieldName": "createdBySubjectSlug", "operator": "EQUAL", "value": "user@example.com"},
                  {"spanAttributeKey": "tfy.model.name", "operator": "STRING_CONTAINS", "value": "openai"},
                  {"gatewayRequestMetadataKey": "foo", "operator": "IN", "value": ["bar1", "bar2"]}
              ],
              "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 completed!")
  ```
</CodeGroup>