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

> Filter logs by various criteria

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

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


## OpenAPI

````yaml POST /api/v1/customer/{chain}/logs/filter
openapi: 3.1.0
info:
  title: SonarX EVM API - Logs
  description: Query event logs emitted by smart contracts on EVM-compatible networks.
  version: 1.0.0
servers:
  - url: https://api-gateway.sonarx.com
    description: Production API
security:
  - apiKey: []
tags:
  - name: Logs
    description: Query event logs emitted by smart contracts
paths:
  /api/v1/customer/{chain}/logs/filter:
    post:
      tags:
        - Logs
      summary: Filter Logs
      description: >-
        Filter logs by various criteria. Essential for tracking events, token
        transfers, and smart contract activity. Use either block range or
        datetime range, not both. Block range cannot exceed 100 blocks.
      operationId: filterLogs
      parameters:
        - $ref: '#/components/parameters/ChainPath'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LogFilterRequest'
            examples:
              byBlockRange:
                summary: Filter by block range only
                value:
                  from_block: 81901160
                  to_block: 81901165
              byAddress:
                summary: Filter by contract address
                value:
                  from_block: 81901160
                  to_block: 81901165
                  address: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359'
              byEventSigHashes:
                summary: Filter by event signature (ERC-20 Transfer)
                value:
                  from_block: 81901160
                  to_block: 81901165
                  event_sig_hashes:
                    - >-
                      0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef
              byAddressAndEventSig:
                summary: Filter by address and event signature
                value:
                  from_block: 81901160
                  to_block: 81901165
                  address: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359'
                  event_sig_hashes:
                    - >-
                      0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef
      responses:
        '200':
          description: Filtered logs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LogFilterResponse'
        '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:
    LogFilterRequest:
      type: object
      description: >-
        Request body for filtering logs. 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.
        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: Contract address(es) to filter by (optional, max 10 addresses)
        event_sig_hashes:
          oneOf:
            - type: string
              pattern: ^0x[a-fA-F0-9]{64}$
            - type: array
              items:
                type: string
                pattern: ^0x[a-fA-F0-9]{64}$
              maxItems: 10
          description: >-
            Event signature hash(es) to filter by (optional, max 10). This
            filters against the first topic (topic1) in each log, which contains
            the keccak256 hash of the event signature. For example, the ERC-20
            Transfer event signature hash is
            0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef.
    LogFilterResponse:
      type: object
      properties:
        offset:
          type: integer
        limit:
          type: integer
        result:
          type: array
          items:
            $ref: '#/components/schemas/Log'
        count:
          type: integer
      example:
        offset: 0
        limit: 10
        result:
          - block_number: 81901160
            timestamp: 1768922292
            datetime: '2026-01-20T15:18:12'
            transaction_hash: '0x00dcc066aad65ae4f10c0fc4ec1fac5d3693c12c01d98a9f6a87448be9b26200'
            transaction_index: 66
            transaction_from: '0xef56899ed9b6b4f3b8d0ea4eb7cec948705c8d2c'
            transaction_to: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359'
            log_index: 366
            address: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359'
            data: '0x000000000000000000000000000000000000000000000000000000000050df20'
            topics:
              - >-
                0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef
              - >-
                0x000000000000000000000000ef56899ed9b6b4f3b8d0ea4eb7cec948705c8d2c
              - >-
                0x0000000000000000000000003cb9cc9869a65db10f47fd40fb977331cc7e3c9b
            topic1: '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'
            topic2: '0x000000000000000000000000ef56899ed9b6b4f3b8d0ea4eb7cec948705c8d2c'
            topic3: '0x0000000000000000000000003cb9cc9869a65db10f47fd40fb977331cc7e3c9b'
            topic4: null
            version: 0
        count: 1
    Log:
      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 that emitted this log
        transaction_index:
          type: integer
        transaction_from:
          type: string
          description: Transaction sender
        transaction_to:
          type: string
          description: Transaction recipient
        log_index:
          type: integer
          description: Index of the log within the transaction
        address:
          type: string
          description: Contract address that emitted this log
        data:
          type: string
          description: Non-indexed event data
        topics:
          type: array
          items:
            type: string
          description: Indexed event topics
        topic1:
          type: string
          description: First topic (event signature hash)
        topic2:
          type: string
          nullable: true
        topic3:
          type: string
          nullable: true
        topic4:
          type: string
          nullable: true
        version:
          type: integer
      example:
        block_number: 81901160
        timestamp: 1768922292
        datetime: '2026-01-20T15:18:12'
        transaction_hash: '0x00dcc066aad65ae4f10c0fc4ec1fac5d3693c12c01d98a9f6a87448be9b26200'
        transaction_index: 66
        transaction_from: '0xef56899ed9b6b4f3b8d0ea4eb7cec948705c8d2c'
        transaction_to: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359'
        log_index: 366
        address: '0x3c499c542cef5e3811e1192ce70d8cc03d5c3359'
        data: '0x000000000000000000000000000000000000000000000000000000000050df20'
        topics:
          - '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'
          - '0x000000000000000000000000ef56899ed9b6b4f3b8d0ea4eb7cec948705c8d2c'
          - '0x0000000000000000000000003cb9cc9869a65db10f47fd40fb977331cc7e3c9b'
        topic1: '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef'
        topic2: '0x000000000000000000000000ef56899ed9b6b4f3b8d0ea4eb7cec948705c8d2c'
        topic3: '0x0000000000000000000000003cb9cc9869a65db10f47fd40fb977331cc7e3c9b'
        topic4: null
        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

````