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

# trace_filter | Tempo

> Tempo API method that returns execution traces matching specific filter criteria. Available on Tempo via Chainstack JSON-RPC nodes.

Tempo API method that returns execution traces matching specific filter criteria. This is useful for finding all interactions with a specific contract or address across multiple blocks.

## Parameters

* `filterObject` — the filter object:
  * `fromBlock` — (optional) starting block number (hex)
  * `toBlock` — (optional) ending block number (hex)
  * `fromAddress` — (optional) array of sender addresses to filter
  * `toAddress` — (optional) array of recipient addresses to filter
  * `after` — (optional) offset for pagination
  * `count` — (optional) maximum number of traces to return

## Response

* `result` — array of trace objects matching the filter:
  * `action` — the action object:
    * `from` — sender address
    * `to` — recipient address
    * `callType` — type of call
    * `gas` — gas provided
    * `input` — call data
    * `value` — value transferred
  * `blockHash` — hash of the block
  * `blockNumber` — block number
  * `result` — the result object
  * `subtraces` — number of child traces
  * `traceAddress` — position in the trace tree
  * `transactionHash` — hash of the transaction
  * `transactionPosition` — index in the block
  * `type` — trace type

## `trace_filter` code examples

The following example finds all calls to the pathUSD token contract:

<CodeGroup>
  ```javascript ethers.js theme={"system"}
  const ethers = require('ethers');
  const NODE_URL = "CHAINSTACK_NODE_URL";
  const provider = new ethers.JsonRpcProvider(NODE_URL);

  // pathUSD token address
  const PATHUSD = "0x20c0000000000000000000000000000000000000";

  const traceFilter = async () => {
      const currentBlock = await provider.getBlockNumber();
      const fromBlock = "0x" + (currentBlock - 1000).toString(16);
      const toBlock = "0x" + currentBlock.toString(16);

      const traces = await provider.send("trace_filter", [{
        fromBlock: fromBlock,
        toBlock: toBlock,
        toAddress: [PATHUSD],
        count: 20
      }]);

      console.log(`Found ${traces.length} traces to pathUSD`);

      for (const trace of traces) {
        console.log(`Block ${trace.blockNumber}: ${trace.action.from} -> ${trace.action.to}`);
        console.log(`  Call type: ${trace.action.callType}`);
        console.log(`  Tx: ${trace.transactionHash}`);
      }
    };

  traceFilter();
  ```

  ```python web3.py theme={"system"}
  from web3 import Web3

  node_url = "CHAINSTACK_NODE_URL"
  web3 = Web3(Web3.HTTPProvider(node_url))

  # pathUSD token address
  PATHUSD = "0x20c0000000000000000000000000000000000000"

  current_block = web3.eth.block_number
  from_block = hex(current_block - 1000)
  to_block = hex(current_block)

  result = web3.provider.make_request("trace_filter", [{
      "fromBlock": from_block,
      "toBlock": to_block,
      "toAddress": [PATHUSD],
      "count": 20
  }])

  traces = result['result']
  print(f"Found {len(traces)} traces to pathUSD")

  for trace in traces:
      print(f"Block {trace['blockNumber']}: {trace['action']['from']} -> {trace['action']['to']}")
      print(f"  Call type: {trace['action']['callType']}")
      print(f"  Tx: {trace['transactionHash']}")
  ```

  ```bash cURL theme={"system"}
  curl -X POST "CHAINSTACK_NODE_URL" \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc": "2.0",
      "method": "trace_filter",
      "params": [{
        "fromBlock": "0x564000",
        "toBlock": "0x565000",
        "toAddress": ["0x20c0000000000000000000000000000000000000"],
        "count": 20
      }],
      "id": 1
    }'
  ```
</CodeGroup>


## OpenAPI

````yaml openapi/tempo_node_api/debug_and_trace/trace_filter.json POST /
openapi: 3.0.0
info:
  title: trace_filter Tempo example
  version: 1.0.0
  description: This is an API example for trace_filter for Tempo.
servers:
  - url: https://tempo-mainnet.core.chainstack.com/c3ce2925b51f1ed18719fe8a23bbdccf
security: []
paths:
  /:
    post:
      tags:
        - Debug and trace
      summary: trace_filter
      operationId: tempo-trace-filter
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                jsonrpc:
                  type: string
                  default: '2.0'
                method:
                  type: string
                  default: trace_filter
                params:
                  type: array
                  items: {}
                  default:
                    - fromBlock: '0x564000'
                      toBlock: '0x565000'
                      toAddress:
                        - '0x20c0000000000000000000000000000000000000'
                      count: 10
                  description: Filter object with block range and address filters
                id:
                  type: integer
                  default: 1
      responses:
        '200':
          description: Array of matching traces
          content:
            application/json:
              schema:
                type: object
                properties:
                  jsonrpc:
                    type: string
                  id:
                    type: integer
                  result:
                    type: array
                    items:
                      type: object
                    description: Array of trace objects matching the filter

````