Result Filtering

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

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)

curl -X GET 'https://api.dune.com/api/v1/query/{{query_id}}/results?limit=10&filters=block_time%3E%272024-03-01%27&columns=tx_from%2Ctx_to%2Ctx_hash%2Camount_usd&sort_by=amount_usd%20desc%2Cblock_time' \
-H 'x-dune-api-key:{{api_key}}’

import requests

url = "https://api.dune.com/api/v1/query/{query_id}/results"

headers = {"X-DUNE-API-KEY": "<x-dune-api-key>"}

params = {
    "limit": 10,
    "filters": "block_time > '2024-03-01'",
    "columns": "tx_from,tx_to,tx_hash,amount_usd",
    "sort_by": "amount_usd desc, block_time"
    }

response = requests.request("GET", url, headers=headers, params=params)

print(response.text)

const options = {
    method: 'GET',
    headers: {
        'X-DUNE-API-KEY': '<x-dune-api-key>'
    }
};

const queryParams = new URLSearchParams({
    limit: 10,
    filters: "block_time > '2024-03-01'",
    columns: "tx_from,tx_to,tx_hash,amount_usd",
    sort_by: "amount_usd desc, block_time"
});
const url = `https://api.dune.com/api/v1/query/{query_id}/results?${queryParams}`;

fetch(url, options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));

package main

import (
    "fmt"
    "net/http"
    "io/ioutil"
    "net/url"
)

func main() {
    url := "https://api.dune.com/api/v1/query/{query_id}/results"

    // Create query parameters
    params := url.Values{}
    params.Set("limit", "10")
    params.Set("filters", "block_time > '2024-03-01'")
    params.Set("columns", "tx_from,tx_to,tx_hash,amount_usd")
    params.Set("sort_by", "amount_usd desc, block_time")

    // Add parameters to URL
    fullURL := fmt.Sprintf("%s?%s", url, params.Encode())

    req, _ := http.NewRequest("GET", fullURL, nil)

    req.Header.Add("X-DUNE-API-KEY", "<x-dune-api-key>")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))
}

<?php

$curl = curl_init();

$url = "https://api.dune.com/api/v1/query/{query_id}/results";
$queryParams = http_build_query([
    'limit' => 10,
    'filters' => "block_time > '2024-03-01'",
    'columns' => "tx_from,tx_to,tx_hash,amount_usd",
    'sort_by' => "amount_usd desc, block_time",
]);
$url .= '?' . $queryParams;

curl_setopt_array($curl, [
    CURLOPT_URL => $url,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "X-DUNE-API-KEY: <x-dune-api-key>"
    ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $response;
}
?>

import kong.unirest.HttpResponse;
import kong.unirest.Unirest;

public class Main {
    public static void main(String[] args) {
        HttpResponse<String> response = Unirest.get("https://api.dune.com/api/v1/query/{query_id}/results")
                .header("X-DUNE-API-KEY", "<x-dune-api-key>")
                .queryString("limit", 10)
                .queryString("filters", "block_time > '2024-03-01'")
                .queryString("columns", "tx_from,tx_to,tx_hash,amount_usd")
                .queryString("sort_by", "amount_usd desc, block_time")
                .asString();

        System.out.println(response.getBody());
    }
}

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

Always filter time ranges

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"

Combine filters with column selection

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"

Use IN for multiple values

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

Be specific with data types

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

Handle special column names

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

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

Introduction

Quick Start

Agents

Executions and Results

Query Management

Data Uploads

Datasets

Materialized Views

Pipelines

Account Management

Post-processing

Webhooks

Client SDKs

Resources

Overview

Example Filtering Request

Filtering Parameters

`filters`

`columns`

Common Filtering Patterns

Filter by Time Range

Filter by Value Thresholds

Filter by Category

Complex Conditions

Filter with Column Selection

Real-World Examples

Example 1: Whale Transactions

Example 2: Protocol-Specific Analytics

Example 3: Token-Specific Monitoring

Example 4: Multi-Chain Analysis

Filtering Best Practices

Limitations

Filtered Response

​Overview

​Example Filtering Request

​Filtering Parameters

​filters

​columns

​Common Filtering Patterns

​Filter by Time Range

​Filter by Value Thresholds

​Filter by Category

​Complex Conditions

​Filter with Column Selection

​Real-World Examples

​Example 1: Whale Transactions

​Example 2: Protocol-Specific Analytics

​Example 3: Token-Specific Monitoring

​Example 4: Multi-Chain Analysis

​Filtering Best Practices

​Limitations

​Filtered Response

Overview

Example Filtering Request

Filtering Parameters

`filters`

`columns`

Common Filtering Patterns

Filter by Time Range

Filter by Value Thresholds

Filter by Category

Complex Conditions

Filter with Column Selection

Real-World Examples

Example 1: Whale Transactions

Example 2: Protocol-Specific Analytics

Example 3: Token-Specific Monitoring

Example 4: Multi-Chain Analysis

Filtering Best Practices

Limitations

Filtered Response