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

# Filter Traces

> Filter traces by various criteria

<Info>
  **Polygon Data Availability**: Polygon traces are only available from January 2025 onwards.
</Info>

<Info>
  **Block Range Limit**: Block range queries cannot exceed 100 blocks.
</Info>

<Warning>
  **Range Filter Constraint**: Use either block range (`from_block`/`to_block`) OR datetime range (`from_datetime`/`to_datetime`), but not both simultaneously. These filter pairs are mutually exclusive.
</Warning>


## OpenAPI

````yaml POST /api/v1/customer/{chain}/traces/filter
openapi: 3.1.0
info:
  title: SonarX EVM API - Traces
  description: >-
    Query execution traces for transactions and blocks on EVM-compatible
    networks.
  version: 1.0.0
servers:
  - url: https://api-gateway.sonarx.com
    description: Production API
security:
  - apiKey: []
tags:
  - name: Traces
    description: Query execution traces for transactions and blocks
paths:
  /api/v1/customer/{chain}/traces/filter:
    post:
      tags:
        - Traces
      summary: Filter Traces
      description: >-
        Filter traces by various criteria. Essential for finding all
        interactions with specific contracts or addresses. Use either block
        range or datetime range, not both. Block range cannot exceed 100 blocks.
      operationId: filterTraces
      parameters:
        - $ref: '#/components/parameters/ChainPath'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TraceFilterRequest'
            examples:
              byBlockRange:
                summary: Filter by block range
                value:
                  from_block: 81901160
                  to_block: 81901165
              byToAddress:
                summary: Filter by recipient address
                value:
                  from_block: 81901160
                  to_block: 81901165
                  to_address: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359'
      responses:
        '200':
          description: Filtered traces
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TraceFilterResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  parameters:
    ChainPath:
      name: chain
      in: path
      description: The blockchain network to query
      required: true
      schema:
        type: string
        enum:
          - polygon
        example: polygon
    Limit:
      name: limit
      in: query
      description: Maximum number of results (1-50)
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 10
    Offset:
      name: offset
      in: query
      description: Number of results to skip for pagination
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
  schemas:
    TraceFilterRequest:
      type: object
      description: >-
        Request body for filtering traces. Validation rules: (1) Must provide
        either block range OR datetime range, not both and not neither. (2) When
        using block range, both from_block AND to_block are required. (3) When
        using datetime range, both from_datetime AND to_datetime are required.
        (4) to_block must be >= from_block. (5) to_datetime must be >=
        from_datetime. (6) Block range cannot exceed 100 blocks.
      properties:
        from_block:
          type: integer
          minimum: 0
          description: Start block number. Required if using block range.
        to_block:
          type: integer
          minimum: 0
          description: >-
            End block number. Required if using block range. Must be >=
            from_block and within 100 blocks.
        from_datetime:
          type: string
          format: date-time
          description: >-
            Start datetime (ISO 8601, timezone required, e.g.,
            2024-01-15T10:30:00Z or 2024-01-15T10:30:00+00:00). Required if
            using datetime range.
        to_datetime:
          type: string
          format: date-time
          description: >-
            End datetime (ISO 8601, timezone required, e.g.,
            2024-01-15T10:30:00Z or 2024-01-15T10:30:00+00:00). Required if
            using datetime range. Must be >= from_datetime.
        from_address:
          oneOf:
            - type: string
              pattern: ^0x[a-fA-F0-9]{40}$
            - type: array
              items:
                type: string
                pattern: ^0x[a-fA-F0-9]{40}$
              maxItems: 10
          description: Sender address(es) to filter by (max 10 addresses)
        to_address:
          oneOf:
            - type: string
              pattern: ^0x[a-fA-F0-9]{40}$
            - type: array
              items:
                type: string
                pattern: ^0x[a-fA-F0-9]{40}$
              maxItems: 10
          description: Recipient address(es) to filter by (max 10 addresses)
    TraceFilterResponse:
      type: object
      properties:
        offset:
          type: integer
        limit:
          type: integer
        result:
          type: array
          items:
            $ref: '#/components/schemas/Trace'
        count:
          type: integer
      example:
        offset: 0
        limit: 10
        result:
          - block_number: 81901160
            timestamp: 1768922292
            datetime: '2026-01-20T15:18:12'
            transaction_hash: '0x2e8c9673c8d527e105a0b24036f2f0a1acbb0cb428a8360a8d9a1cf42419e9c6'
            transaction_index: 0
            trace_address: ''
            transaction_from: '0xca8762c845a00d5c162a5ea0c53d4a49459133f9'
            transaction_to: '0xc2132d05d31c914a87c6611c10748aeb04b58e8f'
            transaction_status: true
            call_type: call
            from_address: '0xca8762c845a00d5c162a5ea0c53d4a49459133f9'
            to_address: '0xc2132d05d31c914a87c6611c10748aeb04b58e8f'
            gas: 76872
            gas_used: 30602
            gas_refund: 46270
            value: '0'
            subtraces: 1
            type: call
            input: >-
              0x23b872dd0000000000000000000000006908194b2a96dc0dade8840bf911511a34801796000000000000000000000000c3eafcbd3fbcd393e3b80b3a87a8626a1934ba060000000000000000000000000000000000000000000000000000000001749c81
            output: '0x0000000000000000000000000000000000000000000000000000000000000001'
            error: null
            function_signature: '0x23b872dd'
            version: 0
        count: 1
    Trace:
      type: object
      properties:
        block_number:
          type: integer
          description: Block number
        timestamp:
          type: integer
          description: Unix timestamp
        datetime:
          type: string
          format: date-time
        transaction_hash:
          type: string
          description: Transaction hash
        transaction_index:
          type: integer
        trace_address:
          type: string
          description: Position in trace tree (e.g., '0', '0.0', '0.0.0')
        transaction_from:
          type: string
          description: Original transaction sender
        transaction_to:
          type: string
          description: Original transaction recipient
        transaction_status:
          type: boolean
          description: Overall transaction success
        call_type:
          type: string
          description: Type of call (call, delegatecall, staticcall, create)
        from_address:
          type: string
          description: Sender of this trace call
        to_address:
          type: string
          description: Recipient of this trace call
        gas:
          type: integer
          description: Gas provided
        gas_used:
          type: integer
          description: Gas used
        gas_refund:
          type: integer
          description: Gas refunded
        value:
          type: string
          description: Value in wei
        subtraces:
          type: integer
          description: Number of sub-calls
        type:
          type: string
          description: Trace type (call, create, suicide)
        input:
          type: string
          description: Input data
        output:
          type: string
          description: Output data
        error:
          type: string
          nullable: true
          description: Error message if failed
        function_signature:
          type: string
          description: Function selector (first 4 bytes of input)
        version:
          type: integer
      example:
        block_number: 81911103
        timestamp: 1768942178
        datetime: '2026-01-20T20:49:38'
        transaction_hash: '0x0063079708b5fab44762765a01c17ab2754ebc15cb9ecd0e14fcbbd520452c27'
        transaction_index: 80
        trace_address: ''
        transaction_from: '0xb63c1246a11edc1e784c39ab95295e4180c5071b'
        transaction_to: '0x9ead30c8518a19f0b493eea1bd5af8fcc5fd4ba2'
        transaction_status: true
        call_type: call
        from_address: '0xb63c1246a11edc1e784c39ab95295e4180c5071b'
        to_address: '0x9ead30c8518a19f0b493eea1bd5af8fcc5fd4ba2'
        gas: 200
        gas_used: 0
        gas_refund: 200
        value: '100000000000'
        subtraces: 0
        type: call
        input: 0x
        output: 0x
        error: null
        function_signature: 0x
        version: 0
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
      required:
        - detail
  responses:
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: apikey
      description: API key for authentication

````