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

# Traces

> SDK methods to query spans and manage distributed traces collected by TrueFoundry.

## Methods

<Accordion title="query_spans">
  Parameters

  #### Parameters

  <ParamField body="start_time" type="str" required>
    Start time in ISO 8601 format (e.g., 2025-03-12T00:00:09.872Z)
  </ParamField>

  <ParamField body="end_time" type="typing.Optional[str]">
    End time in ISO 8601 format (e.g., 2025-03-12T00:10:00.000Z). Defaults to current time if not provided.
  </ParamField>

  <ParamField body="trace_ids" type="typing.Optional[typing.Sequence[str]]">
    Array of trace IDs to filter by
  </ParamField>

  <ParamField body="span_ids" type="typing.Optional[typing.Sequence[str]]">
    Array of span IDs to filter by
  </ParamField>

  <ParamField body="parent_span_ids" type="typing.Optional[typing.Sequence[str]]">
    Array of parent span IDs to filter by
  </ParamField>

  <ParamField body="created_by_subject_types" type="typing.Optional[typing.Sequence[SubjectType]]">
    [🔗 SubjectType](/docs/truefoundry_sdk/enums#subjecttype)

    Array of subject types to filter by
  </ParamField>

  <ParamField body="created_by_subject_slugs" type="typing.Optional[typing.Sequence[str]]">
    Array of subject slugs to filter by
  </ParamField>

  <ParamField body="application_names" type="typing.Optional[typing.Sequence[str]]">
    Array of application names to filter by
  </ParamField>

  <ParamField body="limit" type="typing.Optional[int]">
    The maximum number of spans to return per page. Defaults to 200 if not provided.
  </ParamField>

  <ParamField body="sort_direction" type="typing.Optional[SortDirection]">
    [🔗 SortDirection](/docs/truefoundry_sdk/enums#sortdirection)

    Sort direction for results based on time. Defaults to descending (latest first)
  </ParamField>

  <ParamField body="page_token" type="typing.Optional[str]">
    An opaque string that should be passed as-is from previous response for fetching the next page. Pass `$response.pagination.nextPageToken` from previous response for fetching the next page.
  </ParamField>

  <ParamField body="tracing_project_fqn" type="typing.Optional[str]">
    Tracing project FQN (e.g., truefoundry:tracing-project:tfy-default)
  </ParamField>

  <ParamField body="data_routing_destination" type="typing.Optional[str]">
    Data Routing Destination. One of tracingProjectFqn or dataRoutingDestination is required.
  </ParamField>

  <ParamField body="filters" type="typing.Optional[typing.Sequence[QuerySpansRequestFiltersItem]]">
    [🔗 QuerySpansRequestFiltersItem](/docs/truefoundry_sdk/types#queryspansrequestfiltersitem)

    Array of filters
  </ParamField>

  <ParamField body="include_feedbacks" type="typing.Optional[bool]">
    When true, feedback data is included in the response. When false, feedback data is excluded (returns empty array).
  </ParamField>

  #### Returns

  <ResponseField name="SyncPager[TraceSpan, QuerySpansResponse]" type="SyncPager[TraceSpan, QuerySpansResponse]">
    [🔗 QuerySpansResponse](/docs/truefoundry_sdk/types#queryspansresponse)

    Returns all the spans matching the query.
  </ResponseField>

  #### Usage

  ```python lines theme={"dark"}
  from truefoundry import TrueFoundry

  client = TrueFoundry(
      api_key="YOUR_API_KEY",
      base_url="https://yourhost.com/path/to/api",
  )

  client.traces.query_spans(
      start_time="value",
      end_time="value",
      trace_ids="value",
      span_ids="value",
      parent_span_ids="value",
      created_by_subject_types="value",
      created_by_subject_slugs="value",
      application_names="value",
      limit=10,
      sort_direction="value",
      page_token="value",
      tracing_project_fqn="value",
      data_routing_destination="value",
      filters="value",
      include_feedbacks="value",
  )
  ```
</Accordion>