> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agno.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Traces with Advanced Filters

> Search traces using the FilterExpr DSL for complex, composable queries.

**Group By Mode:**
- `run` (default): Returns `PaginatedResponse[TraceDetail]` with full span trees
- `session`: Returns `PaginatedResponse[TraceSessionStats]` with aggregated session stats

**Supported Operators:**
- Comparison: `EQ`, `NEQ`, `GT`, `GTE`, `LT`, `LTE`
- Inclusion: `IN`
- String matching: `CONTAINS` (case-insensitive substring), `STARTSWITH` (prefix)
- Logical: `AND`, `OR`, `NOT`

**Filterable Fields:**
trace_id, name, status, start_time, end_time, duration_ms, run_id, session_id, user_id, agent_id, team_id, workflow_id, created_at

**Example Request Body (runs):**
```json
{
  "filter": {"op": "EQ", "key": "status", "value": "OK"},
  "group_by": "run",
  "page": 1,
  "limit": 20
}
```

**Example Request Body (sessions):**
```json
{
  "filter": {"op": "CONTAINS", "key": "agent_id", "value": "stock"},
  "group_by": "session",
  "page": 1,
  "limit": 20
}
```



## OpenAPI

````yaml post /traces/search
openapi: 3.1.0
info:
  title: Agno API Reference
  description: The all-in-one, private, secure agent platform that runs in your cloud.
  version: 2.7.2
servers: []
security: []
paths:
  /traces/search:
    post:
      tags:
        - Traces
        - Traces
      summary: Search Traces with Advanced Filters
      description: >-
        Search traces using the FilterExpr DSL for complex, composable queries.


        **Group By Mode:**

        - `run` (default): Returns `PaginatedResponse[TraceDetail]` with full
        span trees

        - `session`: Returns `PaginatedResponse[TraceSessionStats]` with
        aggregated session stats


        **Supported Operators:**

        - Comparison: `EQ`, `NEQ`, `GT`, `GTE`, `LT`, `LTE`

        - Inclusion: `IN`

        - String matching: `CONTAINS` (case-insensitive substring), `STARTSWITH`
        (prefix)

        - Logical: `AND`, `OR`, `NOT`


        **Filterable Fields:**

        trace_id, name, status, start_time, end_time, duration_ms, run_id,
        session_id, user_id, agent_id, team_id, workflow_id, created_at


        **Example Request Body (runs):**

        ```json

        {
          "filter": {"op": "EQ", "key": "status", "value": "OK"},
          "group_by": "run",
          "page": 1,
          "limit": 20
        }

        ```


        **Example Request Body (sessions):**

        ```json

        {
          "filter": {"op": "CONTAINS", "key": "agent_id", "value": "stock"},
          "group_by": "session",
          "page": 1,
          "limit": 20
        }

        ```
      operationId: search_traces
      parameters:
        - name: db_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Database ID to query traces from
            title: Db Id
          description: Database ID to query traces from
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TraceSearchRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/PaginatedResponse_TraceDetail_'
                  - $ref: '#/components/schemas/PaginatedResponse_TraceSessionStats_'
                title: Response Search Traces
        '400':
          description: Invalid filter expression
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthenticatedResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
      security:
        - HTTPBearer: []
components:
  schemas:
    TraceSearchRequest:
      properties:
        filter:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Filter
          description: >-
            FilterExpr DSL as JSON dict. Supports operators: EQ, NEQ, GT, GTE,
            LT, LTE, IN, CONTAINS, STARTSWITH, AND, OR, NOT.
        group_by:
          $ref: '#/components/schemas/TraceSearchGroupBy'
          description: >-
            Grouping mode: 'run' returns individual TraceDetail, 'session'
            returns aggregated TraceSessionStats.
          default: run
        page:
          type: integer
          minimum: 1
          title: Page
          description: Page number (1-indexed)
          default: 1
        limit:
          type: integer
          maximum: 100
          minimum: 1
          title: Limit
          description: Number of traces per page (max 100)
          default: 20
      type: object
      title: TraceSearchRequest
      description: >-
        Request body for POST /traces/search with advanced filtering.


        The filter field accepts a FilterExpr DSL dict supporting composable
        queries

        with AND/OR/NOT logic and operators like EQ, NEQ, GT, GTE, LT, LTE, IN,
        CONTAINS, STARTSWITH.


        Example for run grouping (default):
            {
                "filter": {
                    "op": "AND",
                    "conditions": [
                        {"op": "EQ", "key": "status", "value": "OK"},
                        {"op": "CONTAINS", "key": "user_id", "value": "admin"}
                    ]
                },
                "group_by": "run",
                "page": 1,
                "limit": 20
            }

        Example for session grouping:
            {
                "filter": {"op": "EQ", "key": "agent_id", "value": "my-agent"},
                "group_by": "session",
                "page": 1,
                "limit": 20
            }
    PaginatedResponse_TraceDetail_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/TraceDetail'
          type: array
          title: Data
          description: List of items for the current page
        meta:
          $ref: '#/components/schemas/PaginationInfo'
          description: Pagination metadata
      type: object
      required:
        - data
        - meta
      title: PaginatedResponse[TraceDetail]
    PaginatedResponse_TraceSessionStats_:
      properties:
        data:
          items:
            $ref: '#/components/schemas/TraceSessionStats'
          type: array
          title: Data
          description: List of items for the current page
        meta:
          $ref: '#/components/schemas/PaginationInfo'
          description: Pagination metadata
      type: object
      required:
        - data
        - meta
      title: PaginatedResponse[TraceSessionStats]
    BadRequestResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Error detail message
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
          description: Error code for categorization
      type: object
      required:
        - detail
      title: BadRequestResponse
      example:
        detail: Bad request
        error_code: BAD_REQUEST
    UnauthenticatedResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Error detail message
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
          description: Error code for categorization
      type: object
      required:
        - detail
      title: UnauthenticatedResponse
      example:
        detail: Unauthenticated access
        error_code: UNAUTHENTICATED
    NotFoundResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Error detail message
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
          description: Error code for categorization
      type: object
      required:
        - detail
      title: NotFoundResponse
      example:
        detail: Not found
        error_code: NOT_FOUND
    ValidationErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Error detail message
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
          description: Error code for categorization
      type: object
      required:
        - detail
      title: ValidationErrorResponse
      example:
        detail: Validation error
        error_code: VALIDATION_ERROR
    InternalServerErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
          description: Error detail message
        error_code:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Code
          description: Error code for categorization
      type: object
      required:
        - detail
      title: InternalServerErrorResponse
      example:
        detail: Internal server error
        error_code: INTERNAL_SERVER_ERROR
    TraceSearchGroupBy:
      type: string
      enum:
        - run
        - session
      title: TraceSearchGroupBy
      description: Grouping options for trace search results.
    TraceDetail:
      properties:
        trace_id:
          type: string
          title: Trace Id
          description: Unique trace identifier
        name:
          type: string
          title: Name
          description: Trace name (usually root span name)
        status:
          type: string
          title: Status
          description: Overall status (OK, ERROR)
        duration:
          type: string
          title: Duration
          description: Human-readable total duration
        start_time:
          type: string
          format: date-time
          title: Start Time
          description: Trace start time (Pydantic auto-serializes to ISO 8601)
        end_time:
          type: string
          format: date-time
          title: End Time
          description: Trace end time (Pydantic auto-serializes to ISO 8601)
        total_spans:
          type: integer
          title: Total Spans
          description: Total number of spans in this trace
        error_count:
          type: integer
          title: Error Count
          description: Number of spans with errors
        input:
          anyOf:
            - type: string
            - type: 'null'
          title: Input
          description: Input to the agent/workflow
        output:
          anyOf:
            - type: string
            - type: 'null'
          title: Output
          description: Output from the agent/workflow
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Error message if status is ERROR
        run_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Run Id
          description: Associated run ID
        session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Session Id
          description: Associated session ID
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
          description: Associated user ID
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
          description: Associated agent ID
        team_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Team Id
          description: Associated team ID
        workflow_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workflow Id
          description: Associated workflow ID
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Time when trace was created (Pydantic auto-serializes to ISO 8601)
        tree:
          items:
            $ref: '#/components/schemas/TraceNode'
          type: array
          title: Tree
          description: Hierarchical tree of spans (root nodes)
      type: object
      required:
        - trace_id
        - name
        - status
        - duration
        - start_time
        - end_time
        - total_spans
        - error_count
        - created_at
        - tree
      title: TraceDetail
      description: Detailed trace information with hierarchical span tree
    PaginationInfo:
      properties:
        page:
          type: integer
          minimum: 0
          title: Page
          description: Current page number (0-indexed)
          default: 0
        limit:
          type: integer
          minimum: 1
          title: Limit
          description: Number of items per page
          default: 20
        total_pages:
          type: integer
          minimum: 0
          title: Total Pages
          description: Total number of pages
          default: 0
        total_count:
          type: integer
          minimum: 0
          title: Total Count
          description: Total count of items
          default: 0
        search_time_ms:
          type: number
          minimum: 0
          title: Search Time Ms
          description: Search execution time in milliseconds
          default: 0
      type: object
      title: PaginationInfo
    TraceSessionStats:
      properties:
        session_id:
          type: string
          title: Session Id
          description: Session identifier
        user_id:
          anyOf:
            - type: string
            - type: 'null'
          title: User Id
          description: User ID associated with the session
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
          description: Agent ID(s) used in the session
        team_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Team Id
          description: Team ID associated with the session
        workflow_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Workflow Id
          description: Workflow ID associated with the session
        total_traces:
          type: integer
          title: Total Traces
          description: Total number of traces in this session
        first_trace_at:
          type: string
          format: date-time
          title: First Trace At
          description: Time of first trace (Pydantic auto-serializes to ISO 8601)
        last_trace_at:
          type: string
          format: date-time
          title: Last Trace At
          description: Time of last trace (Pydantic auto-serializes to ISO 8601)
      type: object
      required:
        - session_id
        - total_traces
        - first_trace_at
        - last_trace_at
      title: TraceSessionStats
      description: Aggregated trace statistics grouped by session
    TraceNode:
      properties:
        id:
          type: string
          title: Id
          description: Span ID
        name:
          type: string
          title: Name
          description: Span name (e.g., 'agent.run', 'llm.invoke')
        type:
          type: string
          title: Type
          description: Span kind (AGENT, TEAM, WORKFLOW, LLM, TOOL)
        duration:
          type: string
          title: Duration
          description: Human-readable duration (e.g., '123ms', '1.5s')
        start_time:
          type: string
          format: date-time
          title: Start Time
          description: Start time (Pydantic auto-serializes to ISO 8601)
        end_time:
          type: string
          format: date-time
          title: End Time
          description: End time (Pydantic auto-serializes to ISO 8601)
        status:
          type: string
          title: Status
          description: Status code (OK, ERROR)
        input:
          anyOf:
            - type: string
            - type: 'null'
          title: Input
          description: Input to the span
        output:
          anyOf:
            - type: string
            - type: 'null'
          title: Output
          description: Output from the span
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Error message if status is ERROR
        spans:
          anyOf:
            - items:
                $ref: '#/components/schemas/TraceNode'
              type: array
            - type: 'null'
          title: Spans
          description: Child spans in the trace hierarchy
        step_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Step Type
          description: Workflow step type (Step, Condition, function, Agent, Team)
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: Additional span attributes and data
        extra_data:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Extra Data
          description: Flexible field for custom attributes and additional data
      type: object
      required:
        - id
        - name
        - type
        - duration
        - start_time
        - end_time
        - status
      title: TraceNode
      description: Recursive node structure for rendering trace hierarchy in the frontend
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````