Skip to main content
Unique to Dune: Server-side result filtering is a powerful feature that sets Dune’s API apart. Filter millions of rows using SQL-like WHERE clauses without transferring unnecessary data or processing client-side.

​
Overview

Dune’s API supports sophisticated filtering on all /results endpoints, allowing you to refine query results server-side. Apply filters on rows and columns to dramatically reduce bandwidth and processing time. Benefits:
  • Reduce bandwidth: Only transfer the data you need
  • Save processing time: Filter server-side before data transfer
  • Simplify client code: No need for complex client-side filtering logic
  • Lower costs: Minimize data transfer and API calls
Available on these endpoints: Filtering can be effectively used in conjunction with pagination and sorting to further enhance query efficiency and relevance. See an example of filtering in action with this Dune farcaster frame.

​
Example Filtering Request

  • Python SDK
  • cURL
  • Python
  • Javascript
  • Go
  • PHP
  • Java
from dune_client.client import DuneClient

# setup Dune Python client
dune = DuneClient()

query_result = dune.get_latest_result_dataframe(
    query=3567562 # https://dune.com/queries/3567562
    , filters="overtip_amount > 0"
    , columns=["donor_fname","overtip_amount","days_overtipped","overall_tip_given_amount","overall_avg_tip_amount"]
    , sort_by=["overall_tip_given_amount desc"]
)

print(query_result)

​
Filtering Parameters

​
filters

  • Type: string
  • Description: Allows specifying criteria to filter rows in the result set. It functions similarly to a SQL WHERE clause. If omitted, all results are returned.
  • Use the format <column_name> <operator> <value> for criteria, for example, block_time >= '2024-03-05 15:03'.
  • Combine criteria using parentheses and logical operators AND / OR, e.g., block_time >= '2024-03-05 15:03' AND (project = 'uniswap' OR project = 'balancer').
  • The IN operator is permitted, as in tx_to IN (0x6a3e4b7e23661108aaec70266c468e6c679ae022, 0xdbf89389504e39f03fbb6bdd601aabb6bfbbed71).
  • The NOT operator is not supported; using NOT IN or NOT LIKE will produce an error.
  • For column names with special characters (e.g., spaces, emojis, dashes, dots), enclose them in double quotes: "special, column" = 'ABC'.
  • Values must be strings or numbers. SQL expressions like now() - interval '1' day are not allowed.
  • Dates and times should be formatted as strings, e.g., block_time > '2023-01-03'.

​
columns

  • Type: string
  • Description: Specifies the column names to include in the result set. If omitted, all columns are returned.
  • List column names without spaces, e.g., use project,block_time,amount_usd instead of project, block_time, amount_usd.
  • Specifying columns helps limit the results to essential data, reducing the data cost of the call.

​
Common Filtering Patterns

​
Filter by Time Range

# Last 24 hours
filters="block_time > '2024-03-05'"

# Specific time range
filters="block_time >= '2024-03-01' AND block_time < '2024-04-01'"

# Recent data (note: relative time expressions are NOT supported in filters)
# Instead, calculate the date client-side
filters="block_time > '2024-03-10 15:30'"

​
Filter by Value Thresholds

# Transactions above $1000
filters="amount_usd > 1000"

# Volume between ranges
filters="volume_usd >= 10000 AND volume_usd <= 100000"

# Non-null values
filters="amount_usd IS NOT NULL"

​
Filter by Category

# Single protocol
filters="project = 'uniswap'"

# Multiple protocols (using OR)
filters="project = 'uniswap' OR project = 'sushiswap'"

# Using IN operator
filters="project IN ('uniswap', 'sushiswap', 'curve')"

# Specific blockchain
filters="blockchain = 'ethereum'"

​
Complex Conditions

# Combine multiple conditions
filters="blockchain = 'ethereum' AND amount_usd > 1000 AND block_time > '2024-03-01'"

# Use parentheses for grouping
filters="(project = 'uniswap' OR project = 'sushiswap') AND amount_usd > 10000"

# Filter with pattern matching
filters="token_symbol LIKE 'WETH%'"

# Address filtering
filters="tx_to IN ('0x6a3e4b7e23661108aaec70266c468e6c679ae022', '0xdbf89389504e39f03fbb6bdd601aabb6bfbbed71')"

​
Filter with Column Selection

# Python SDK example: Get only specific columns for large trades
results = dune.get_latest_result_dataframe(
    query=3493826,
    filters="amount_usd > 10000 AND blockchain = 'ethereum'",
    columns="tx_hash,tx_from,tx_to,amount_usd,block_time"
)
Performance tip: Combine filtering with column selection to minimize data transfer. For example, instead of fetching all 50 columns for millions of rows, fetch only the 5 columns you need for 1000 filtered rows.

​
Real-World Examples

​
Example 1: Whale Transactions

from dune_client import DuneClient

dune = DuneClient(api_key="YOUR_API_KEY")

# Get large USDC transfers in the last day
results = dune.get_latest_result_dataframe(
    query=3493826,
    filters="token_symbol = 'USDC' AND amount_usd > 1000000 AND block_time > '2024-03-10'",
    columns="tx_hash,tx_from,tx_to,amount_usd,block_time",
    sort_by="amount_usd desc"
)

print(f"Found {len(results)} whale transactions")

​
Example 2: Protocol-Specific Analytics

import { DuneClient } from '@duneanalytics/client';

const dune = new DuneClient('YOUR_API_KEY');

// Get Uniswap V3 trades on Arbitrum
const results = await dune.getLatestResults({
  queryId: 3493826,
  filters: "project = 'uniswap' AND version = '3' AND blockchain = 'arbitrum'",
  columns: "trader,token_bought_symbol,token_sold_symbol,amount_usd",
  limit: 100
});

​
Example 3: Token-Specific Monitoring

# Monitor recent trades for a specific token pair
curl -X GET \
  'https://api.dune.com/api/v1/query/3493826/results?filters=token_bought_symbol%20%3D%20%27WETH%27%20AND%20token_sold_symbol%20%3D%20%27USDC%27%20AND%20block_time%20%3E%20%272024-03-10%27&columns=amount_usd%2Cprice%2Cblock_time&sort_by=block_time%20desc' \
  -H 'X-DUNE-API-KEY: YOUR_API_KEY'

​
Example 4: Multi-Chain Analysis

# Compare volumes across chains for the same protocol
blockchains = ['ethereum', 'polygon', 'arbitrum', 'optimism']

for chain in blockchains:
    results = dune.get_latest_result_dataframe(
        query=3493826,
        filters=f"blockchain = '{chain}' AND project = 'uniswap'",
        columns="blockchain,amount_usd"
    )
    total_volume = results['amount_usd'].sum()
    print(f"{chain}: ${total_volume:,.2f}")

​
Filtering Best Practices

Reduce the amount of data scanned by filtering by block_time:
# ✅ Good - filters recent data
filters="block_time > '2024-03-01' AND amount_usd > 1000"

# ❌ Less efficient - scans all historical data
filters="amount_usd > 1000"
Minimize bandwidth by only requesting needed columns:
# ✅ Optimal - filtered rows, selected columns
filters="amount_usd > 10000"&columns="tx_hash,amount_usd,block_time"

# ❌ Wasteful - fetches all columns
filters="amount_usd > 10000"
More efficient than multiple OR conditions:
# ✅ Better
filters="blockchain IN ('ethereum', 'polygon', 'arbitrum')"

# ✅ Also valid but longer
filters="blockchain = 'ethereum' OR blockchain = 'polygon' OR blockchain = 'arbitrum'"
Use proper quoting for strings, no quotes for numbers:
# ✅ Correct
filters="blockchain = 'ethereum' AND amount_usd > 1000"

# ❌ Wrong - amount_usd should not be quoted
filters="blockchain = 'ethereum' AND amount_usd > '1000'"
Use double quotes for columns with special characters:
# ✅ Correct for special characters
filters="\"token.symbol\" = 'USDC'"

# ✅ No quotes needed for normal names
filters="token_symbol = 'USDC'"

​
Limitations

  • No SQL expressions: Filters must use literal values. Expressions like now() - interval '1' day are not supported. Calculate values client-side instead.
  • No NOT operator: NOT IN and NOT LIKE are not supported. Use positive conditions instead.
  • No subqueries: Filters cannot contain subqueries. Use parameterized queries for complex logic.
  • String and number values only: Filters only support string and numeric literals.

​
Filtered Response

    {
        "execution_id": "01HR8AGD6CWGHGP1BN3Z1SJ4MD",
        "query_id": 3493826,
        "is_execution_finished": true,
        "state": "QUERY_STATE_COMPLETED",
        "submitted_at": "2024-03-05T22:07:22.828653Z",
        "expires_at": "2024-06-03T22:07:53.36647Z",
        "execution_started_at": "2024-03-05T22:07:24.013663281Z",
        "execution_ended_at": "2024-03-05T22:07:53.366469062Z",
        "result": {
            "rows": [
                {
                    "amount_usd": null,
                    "block_time": "2024-03-05 20:50:59.000 UTC",
                    "tx_from": "0x38032f326436fdb9c7a9b359e90010f86b8ab482",
                    "tx_hash": "0xce6f59cf2f0b395d8fc33e49d1f5db5686be95555135fd8126bc7c59327cd9be",
                    "tx_to": "0x061b87122ed14b9526a813209c8a59a633257bab"
                },
                {
                    "amount_usd": null,
                    "block_time": "2024-03-05 20:49:33.000 UTC",
                    "tx_from": "0xb46b909be665d75f833be22c6e6285ba5ad74dfa",
                    "tx_hash": "0x1f1725ebe374b1ffb50047055b793b2be6a8cb07ab75fd685b95e842953da4ca",
                    "tx_to": "0x1111111254eeb25477b68fb85ed929f73a960582"
                },
                {
                    "amount_usd": null,
                    "block_time": "2024-03-05 20:48:53.000 UTC",
                    "tx_from": "0x40014275b332f38423fa0de39939d26c7294ffc0",
                    "tx_hash": "0xb4364656c20007fb1d7bfa93d87fc6fe345a91b10661835d1a54d1ac7761a244",
                    "tx_to": "0x1111111254eeb25477b68fb85ed929f73a960582"
                },
                {
                    "amount_usd": 1397.903560808159,
                    "block_time": "2024-03-05 20:48:03.000 UTC",
                    "tx_from": "0xb46b909be665d75f833be22c6e6285ba5ad74dfa",
                    "tx_hash": "0x818f701a6c7dcf78a090cfd8324da5896005c2a6d8e3ec5ac2c29cfa5e67f5d9",
                    "tx_to": "0x1111111254eeb25477b68fb85ed929f73a960582"
                },
                {
                    "amount_usd": null,
                    "block_time": "2024-03-05 20:47:55.000 UTC",
                    "tx_from": "0x50758bdc1735e94401ed73eb7e8bde482766819c",
                    "tx_hash": "0x1dc342dc397ffa7b433fa64280fe9f4a7e0b51409e9abc9fde61bc9b85c938be",
                    "tx_to": "0x4c4af8dbc524681930a27b2f1af5bcc8062e6fb7"
                },
                {
                    "amount_usd": null,
                    "block_time": "2024-03-05 20:47:55.000 UTC",
                    "tx_from": "0x50758bdc1735e94401ed73eb7e8bde482766819c",
                    "tx_hash": "0x1dc342dc397ffa7b433fa64280fe9f4a7e0b51409e9abc9fde61bc9b85c938be",
                    "tx_to": "0x4c4af8dbc524681930a27b2f1af5bcc8062e6fb7"
                },
                {
                    "amount_usd": null,
                    "block_time": "2024-03-05 20:47:53.000 UTC",
                    "tx_from": "0xfa3dc8db10e7c2f7dfa87e86bba6257066731bc1",
                    "tx_hash": "0x0d34634a9438ce241e2870b23e70a008c8db839ba38daadc1074c9b1a52be7c7",
                    "tx_to": "0xba12222222228d8ba445958a75a0704d566bf2c8"
                },
                {
                    "amount_usd": 2.753641952846242,
                    "block_time": "2024-03-05 20:47:53.000 UTC",
                    "tx_from": "0xfa3dc8db10e7c2f7dfa87e86bba6257066731bc1",
                    "tx_hash": "0x0d34634a9438ce241e2870b23e70a008c8db839ba38daadc1074c9b1a52be7c7",
                    "tx_to": "0xba12222222228d8ba445958a75a0704d566bf2c8"
                },
                {
                    "amount_usd": null,
                    "block_time": "2024-03-05 20:47:53.000 UTC",
                    "tx_from": "0xfa3dc8db10e7c2f7dfa87e86bba6257066731bc1",
                    "tx_hash": "0x0d34634a9438ce241e2870b23e70a008c8db839ba38daadc1074c9b1a52be7c7",
                    "tx_to": "0xba12222222228d8ba445958a75a0704d566bf2c8"
                },
                {
                    "amount_usd": 1798.8186143812122,
                    "block_time": "2024-03-05 20:47:49.000 UTC",
                    "tx_from": "0xb46b909be665d75f833be22c6e6285ba5ad74dfa",
                    "tx_hash": "0xcf8d9873f017a8ba9e624c3bb61bede8e11c194965690026cd394f20c55f896a",
                    "tx_to": "0x1111111254eeb25477b68fb85ed929f73a960582"
                }
            ],
            "metadata": {
                "column_names": [
                    "block_time",
                    "tx_from",
                    "tx_to",
                    "tx_hash",
                    "amount_usd"
                ],
                "row_count": 10,
                "result_set_bytes": 2042,
                "total_row_count": 100,
                "total_result_set_bytes": 56496,
                "datapoint_count": 50,
                "pending_time_millis": 1185,
                "execution_time_millis": 29352
            }
        },
        "next_uri": "https://api.dune.com/api/v1/execution/01HR8AGD6CWGHGP1BN3Z1SJ4MD/results?columns=block_time%2Ctx_from%2Ctx_to%2Ctx_hash%2Camount_usd&filters=block_time+%3E+%272024-03-01%27&limit=10&offset=10",
        "next_offset": 10
    }